diff --git a/README.md b/README.md index 8587c73..3143b03 100644 --- a/README.md +++ b/README.md @@ -8,15 +8,15 @@ This repo contains the documentation for the [AI-on-the-Edge-Device Project](htt 1. When it got merged, the [Github Actions](https://github.com/jomjol/AI-on-the-edge-device-docs/actions) will re-generate the documentation and place it in the `gh-pages` branch. This branch automatically gets populated to the public [Documentation Site](https://jomjol.github.io/AI-on-the-edge-device-docs) ## Migrating existing Wiki Pages -The files from the [AI-on-the-Edge-Device Wiki](https://github.com/jomjol/AI-on-the-edge-device/wiki) got exported and added to this repo. Unless the files are listed in the [docs/nav.yml](docs/nav.yml) file, they will be listed in the **asorted pages** section of the left sidebar. +The files from the [AI-on-the-Edge-Device Wiki](https://github.com/jomjol/AI-on-the-edge-device/wiki) got exported and added to this repo. Unless the files are listed in the [docs/nav.yml](docs/nav.yml) file, they will be listed in the **assorted pages** section of the left sidebar. In the end, we should review all pages from there step by step and add them to the upper part of the navigation. ### Tasks to do - - Make sure there is a top level title (#) and all other chaper headers are on lower levels (##, ###) + - Make sure there is a top level title (#) and all other chapter headers are on lower levels (##, ###) - Check the links in the documents - Fetch included images and place them directly in the [docs/img](docs/img) folder - - Rerwrite to have a clear structure + - Rewrite to have a clear structure ## Editing a page Each page has a link on its top-right corner `Edit on GitHub` which brings you directly to the Github editor. diff --git a/docs/Best-Practice.md b/docs/Best-Practice.md index 8e9af1d..4df3004 100644 --- a/docs/Best-Practice.md +++ b/docs/Best-Practice.md @@ -3,14 +3,14 @@ This page shows some best practices: ## Camera Placement -* Move the Camera as close as possible(~4cm), this will help get rid of reflections. +* Move the Camera as close as possible (~4cm), this will help get rid of reflections. -> focus can be adjusted by turning the outer black ring of the camera. -* If the LED reflections are too strong, put tape over the LED to defuse the light +* If the LED reflections are too strong, put tape over the LED to diffuse the light * Change the ImageSize to QVGA under "Expert mode" configuration when close enough, this will be faster and is often good enough for digital recognition. ## Reflections - * Try to get ride of the reflections by rotating the camera, so that the reflections are at positions, where no number is. + * Try to get rid of the reflections by rotating the camera, so that the reflections are at positions, where no number is. * By using the external LED option, you can place WS2812 LEDs freely away from the main axis. * Users report, that a handy cover foil could also help diff --git a/docs/Configuration-Parameter-Details.md b/docs/Configuration-Parameter-Details.md index b99368f..5ce969d 100644 --- a/docs/Configuration-Parameter-Details.md +++ b/docs/Configuration-Parameter-Details.md @@ -49,7 +49,7 @@ FlipImageSize = false | InitialMirror | Option for initially mirroring the image on the original x-axis | | | InitialRotate | Initial rotation of image before alignment in degree (1...359) | | | FlipImageSize | Changes the aspect ratio after the image rotation to avoid cropping of the rotated imaged | | -| /config/refx.jpg 98, 257 | Link to reference image and corresponding target coordinates | file link is relative to sd-card root | +| /config/refx.jpg 98, 257 | Link to reference image and corresponding target coordinates | file link is relative to SD card root | | SearchFieldX/Y | Search field size in X/Y for finding the reference images [pixel] | | Here two reference images are needed. Therefore rotation and shifting can be compensated. As the alignment is one of the most computing time using part, the search field needs to be limited. The calculation time goes quadratic with the search field size. @@ -123,7 +123,7 @@ Here the post processing and consistency check for the readout can be adjusted | numberX.MaxRateValue | Maximum chance rate from one to the next readout.
This can be specified for each number individual. | | | ErrorMessage | Show error messages | | | numberX.DecimalShift | Shifting of the decimal separator from the default position between digital and analog.
This can be specified for each number individual. | DecimalShift = 2: 123.456 --> 12345.6
DecimalShift = -1: 123.456 --> 12.3456
| -| CheckDigitIncreaseConsistency | This parameter controls, if the digits are checked for a consistent change in comparison to the previous value. This only makes sense, if the last digit is changing very slowly and every single digit is visible (e.g. 4.7 --> 4.8 --> 4.9 --> 5.0 --> 5.1). If single digits are skipped, for example because the digits changes to fast, this should be disabled (e.g. 4.7 --> 5.0 --> 5.1). | | +| CheckDigitIncreaseConsistency | This parameter controls, if the digits are checked for a consistent change in comparison to the previous value. This only makes sense, if the last digit is changing very slowly and every single digit is visible (e.g. 4.7 --> 4.8 --> 4.9 --> 5.0 --> 5.1). If single digits are skipped, for example because the digits changes too quickly, this should be disabled (e.g. 4.7 --> 5.0 --> 5.1). | | ### [MQTT] @@ -170,11 +170,11 @@ DataLogActive = true DataLogRetentionInDays = 3 ``` -This paragraph is used to control the logging of the result data to a spectific folder of SD-Card -> \log\data\data_YYYY-MM-DD.csv +This paragraph is used to control the logging of the result data to a specific folder of SD card -> \log\data\data_YYYY-MM-DD.csv | Parameter | Meaning | Options/Examples | | ---------------------- | -------------------------------------------------------- | -------------------------------------------------- | -| DataLogActive | Activate data logging to SD-Card | | +| DataLogActive | Activate data logging to SD card | | | DataLogRetentionInDays | Number of days, for which the log files should be stored | 0 = keep forever | @@ -210,7 +210,7 @@ This paragraph is used to switch on an extended logging. It is optional and by d | Parameter | Meaning | Options/Examples | | ---------- | ------------------------------------------------------------ | ------------------------------------------------------------ | -| TimeZone | TimeZone of the system can be specified | Central european, with summertime adjustement: `CET-1CEST,M3.5.0,M10.5.0/3` | +| TimeZone | TimeZone of the system can be specified | Central european, with summertime adjustment: `CET-1CEST,M3.5.0,M10.5.0/3` | | TimeServer | An dedicated time server can be specified. | default = `pool.ntp.org` | | Hostname | Additionally to the `wlan.ini` the hostname can be specified. It will be transferred to the `wlan.ini` and initiate a reboot | | | SetupMode | If enabled, the server starts in an initial setup mode. This is automatically disabled at the end of the setup | diff --git a/docs/Configuration.md b/docs/Configuration.md index 563af44..008b05a 100644 --- a/docs/Configuration.md +++ b/docs/Configuration.md @@ -10,7 +10,7 @@ More configuration parameters can be edited by hand in the `config.ini` and corr -If you where using the Version 1 of the watermeter you can easily transfer the configuration to the new system by following the steps in this [migration description](outdated--Migrate-Old-Config-To-New-Config.md) +If you where using the Version 1 of the water meter you can easily transfer the configuration to the new system by following the steps in this [migration description](outdated--Migrate-Old-Config-To-New-Config.md) @@ -77,4 +77,3 @@ The ```config.ini``` here has the same functionality and options, but a slightly ### Integration into Home Assistant Thanks to the help of the user @deadly667 here are some hints for the integration into the home assistant: [[Integration-Home-Assistant]] - diff --git a/docs/Correction Algorithm.md b/docs/Correction Algorithm.md index 554187f..533a0a1 100644 --- a/docs/Correction Algorithm.md +++ b/docs/Correction Algorithm.md @@ -32,11 +32,11 @@ This are value derived from a pointer like meter. This never has the state "N". ##### CheckDigitIncreaseConsistency -If this is enabled an "inteligent" algorithm is used to derive from zero-crossing of discrete digit positions, if the number should have been increased. This is relevant because in some of the digit meters, the increase of a digit to the next number can be seen, before the subdigit has gone through zero. +If this is enabled an "intelligent" algorithm is used to derive from zero-crossing of discrete digit positions, if the number should have been increased. This is relevant because in some of the digit meters, the increase of a digit to the next number can be seen, before the sub-digit has gone through zero. For example: 16.6 --> 16.7 --> 1N.8 --> **17.9** corrected to 16.9 --> 17.0 --> 17.1 -As you can see, the 17.9 is a false reading as the 7 is assumed to be already readable, although the subdigit has not crossed the zero. In this case the CheckDigitIncreaseConsistency algorithm will correct this to 16.9 +As you can see, the 17.9 is a false reading as the 7 is assumed to be already readable, although the sub-digit has not crossed the zero. In this case the CheckDigitIncreaseConsistency algorithm will correct this to 16.9 A detailed description of the algorithm can be found below (not yet ready!) diff --git a/docs/Demo-Mode.md b/docs/Demo-Mode.md index 0737042..a7d36be 100644 --- a/docs/Demo-Mode.md +++ b/docs/Demo-Mode.md @@ -1,7 +1,7 @@ # Demo Mode For Demo and Testing Purpose, the device can use pre-recorded images. -You need to enable it in the configuration (`TakeImage > Demo`) and also provide the needed files on the SD-Card. +You need to enable it in the configuration (`TakeImage > Demo`) and also provide the needed files on the SD card. For each round one image gets used, starting with the first image for the first round. @@ -9,7 +9,7 @@ For the reference image and the alignment also the first image gets used. Once the last image got reached, it starts again with the first one. -## SD-Card Structure +## SD Card Structure ``` demo/ ├── 520.8983.jpg @@ -65,10 +65,10 @@ done Just install the zip file using the OTA Update functionality. ## How does it work -The Demo Mode tries to interfere as less as possible with the normal behavior. Whenever a Cam Framebuffer gets taken (`esp_camera_fb_get()`), it replaces the framebuffer with the image from the SD-Card. +The Demo Mode tries to interfere as less as possible with the normal behavior. Whenever a Cam framebuffer gets taken (`esp_camera_fb_get()`), it replaces the framebuffer with the image from the SD card. -## Example Data of a Watermeter +## Example Data of a Water Meter You can use the following demo images if you want: ![530 00688](https://user-images.githubusercontent.com/1783586/211902363-1b8e4115-5f08-4e25-ace6-bb52e43b3741.jpg){:style="width:200px"} @@ -98,5 +98,3 @@ Animation of it (186 MB!) [![grafik](https://user-images.githubusercontent.com/1783586/211915898-b499e109-7b63-4e21-ba5b-c0a370022f7a.png){:style="width:400px"}](https://user-images.githubusercontent.com/1783586/211915898-b499e109-7b63-4e21-ba5b-c0a370022f7a.png) [Demo_Images_Watermeter_530.00688-532.08243_42_images.zip](https://github.com/jomjol/AI-on-the-edge-device-docs/files/10395893/Demo_Images_Watermeter_530.00688-532.08243_42_images.zip) - - diff --git a/docs/Error-Debugging.md b/docs/Error-Debugging.md index 0f4977e..556a533 100644 --- a/docs/Error-Debugging.md +++ b/docs/Error-Debugging.md @@ -39,11 +39,11 @@ Analyze the debugging output of the serial interface -This typically happens if you have suboptimal "Alignement Marks". A very simple and working solution is to put put higly contrasted stickers on your meter and put "Alignement Marks" on it (see picture below) +This typically happens if you have suboptimal "Alignment Marks". A very simple and working solution is to put put higly contrasted stickers on your meter and put "Alignment Marks" on it (see picture below) -If after those adjustement you still have some issues, you can try to adjust your aligmenet settings in expert mode: +If after those adjustment you still have some issues, you can try to adjust your alignment settings in expert mode: diff --git a/docs/External-LED.md b/docs/External-LED.md index 0a4b4d8..142833b 100644 --- a/docs/External-LED.md +++ b/docs/External-LED.md @@ -1,7 +1,7 @@ ## External LED The internal flash LED is very close to the camera axis. This results in reflection, especially in case of flat glass surfaces such as for power meters. -To circumvent this problem, it is now possible to control external LEDs, which than can be places somewhere else in the setup. As not simples LEDs are used, but RGB leds with a digital interface like WS2812 not only the position, but also the color and intensity of the illumination can now be adjusted. The following image shows a direct comparision of the "old" internal flash LED and two off axis LEDs. +To circumvent this problem, it is now possible to control external LEDs, which than can be places somewhere else in the setup. As not simples LEDs are used, but RGB LEDs with a digital interface like WS2812 not only the position, but also the color and intensity of the illumination can now be adjusted. The following image shows a direct comparison of the "old" internal flash LED and two off axis LEDs. diff --git a/docs/FAQs.md b/docs/FAQs.md index 22ac230..f7831a0 100644 --- a/docs/FAQs.md +++ b/docs/FAQs.md @@ -6,7 +6,7 @@ There are several reasons for the reboot: * Frequent HTML requests * Wrong configuration, missing configuration files -* Unstable hardware - see [[Hardware Compatibility]] +* Unstable hardware - see [Hardware Compatibility](../Hardware-Compatibility). There is a dedicated page about this: [Frequent Reboots](../Frequent-Reboots/). @@ -38,9 +38,10 @@ As mentioned above, the AI algorithm is not perfect. Sometimes it may read an in We can tune the software to _almost_ never report an incorrect value. There is a tradeoff though: the software may report _stale_ values - i.e. it will drop incorrect values for a potentially long period of time, resulting in the meter reading being outdated by hours. If never receiving an incorrect value is important to you, consider tolerating this tradeoff. You can change the following settings to reduce incorrect readings (but potentially increase staleness of data): + * Set a prevalue via the UI, then change `PostProcessing` configuration option `PreValueAgeStartup` to a much larger number (e.g. `43200` = 30 days). * Change `PostProcessing` configuration option `MaxRateType` to be time based instead of absolute. Set `MaxRateValue` to something realistic (e.g. `5` gal/min). You can often find the max flow rate your meter supports directly on the cover. -* Reduce `AutoTimer` configuration option `Intervall` to the lowest it can be (e.g. `3` min). The more often you take readings, the less likely for data staleness to occur. +* Reduce `AutoTimer` configuration option `Interval` to the lowest it can be (e.g. `3` min). The more often you take readings, the less likely for data staleness to occur. ## Even after I have setup everything perfect there is a false reading - especially around the zero crossing (roll over to next number) * The roll over behavior is different for the different meters. E.g.: @@ -48,7 +49,7 @@ You can change the following settings to reduce incorrect readings (but potentia * The neutral position (no rolling) is not perfectly at zero, but rather at something like 7.9 or 8.1, even if it should be exactly 8 * The "PostProcessingAlgo" is trying to judge out of the individual readings, what number it should be. - * For example if the previous number is a "1", but the next number seems to be a "8.9", mos probably there was a "zero crossing" and the number is a "9" and not still an "8" + * For example if the previous number is a "1", but the next number seems to be a "8.9", most probably there was a "zero crossing" and the number is a "9" and not still an "8" * Currently the setting of the algorithm is set to fit most of the meters and cases. But the parameters do not fit perfectly for all situations. Therefore there might be intermediate states, where the reading is false. This is especially the case, at the positions, where the roll over (zero crossing) is just starting. @@ -56,8 +57,3 @@ You can change the following settings to reduce incorrect readings (but potentia Usually after some time and movement of the counters a bit further, the reading is getting back to a stable reading. * To handle this, a parametrized setting would be needed. This is rather complicated to implement as subtle changes make a relevant difference. Currently this is not implemented. So please be a bit patient with your meter :-) - - - - - diff --git a/docs/Frequent-Reboots.md b/docs/Frequent-Reboots.md index 7e4c947..9844b3a 100644 --- a/docs/Frequent-Reboots.md +++ b/docs/Frequent-Reboots.md @@ -99,7 +99,7 @@ This is the most annoying error. The SD card is detected, but the files cannot b ##### PSRAM too low -In order to work, there are 4 MB of PSRAM necessary. Normaly the ESP32CAM is equiped with 8 MB, whereof only 4 MB can be used effectively. +In order to work, there are 4 MB of PSRAM necessary. Normally the ESP32CAM is equipped with 8 MB, whereof only 4 MB can be used effectively. Sometimes, there is hardware, where only 2 MB of PSRAM is present - **even if you have bought a 8 MB module** You can identify the amount of PSRAM in the serial log file: @@ -131,4 +131,3 @@ There are several files needed during on run cycle. If one of this is missing, t * `/config/XXXXX.tflite` (1 time for analog and 1 time for digital) where XXXXX is the file name, that is written in the `config.ini` - diff --git a/docs/Graphical-Configuration.md b/docs/Graphical-Configuration.md index 39099a9..5dfd0b1 100644 --- a/docs/Graphical-Configuration.md +++ b/docs/Graphical-Configuration.md @@ -11,7 +11,7 @@ ## Access to the graphical user interface -The graphical configuration mode can be reached via the "Edit Configuration" button in the main menue (`/index.html`): +The graphical configuration mode can be reached via the "Edit Configuration" button in the main menu (`/index.html`): * @@ -27,13 +27,13 @@ The graphical configuration mode can be reached via the "Edit Configuration" but b. Define alignment structures 3. Definition of ROIs for digits and analog pointers 4. Test the settings -5. Back to main menue ("index.html") +5. Back to main menu ("index.html") ### 1. Edit Config.ini -This is a text editor for the config.ini. Changes commited with the button on the lower left. +This is a text editor for the config.ini. Changes committed with the button on the lower left. * @@ -45,15 +45,15 @@ Details see [Configuration-Parameter-Details](../Configuration-Parameter-Details The reference image is the basis for the coordination of the ROIs. Therefore it is very important, to have a well aligned image, that is not rotated. -**:bangbang: Attention:** Updating the reference image, also means, that all alignment images and ROIs needs to be teached again. Therefore do this step only with caution. +**:bangbang: Attention:** Updating the reference image, also means, that all alignment images and ROIs needs to be taught again. Therefore do this step only with caution. * At first the current image is shown and no adjustment is possible. To reload the actual image push the button "Show actual Reference" (1). To define a new reference image push the button "Create new Reference" (2). -Then the last taken raw image from the camera is loaded. If you want to update this, you can push the button "Make new raw image (raw.jpg)". If you need to mirror your image (e.g. mirror before camera) you can do this by selecting "mirror image". After loading the mirroring (in case checked) and the prerotation angle from the `config.ini` are applied. Then use the rough and fine adjustment to get the image straight aligned (3). +Then the last taken raw image from the camera is loaded. If you want to update this, you can push the button "Make new raw image (raw.jpg)". If you need to mirror your image (e.g. mirror before camera) you can do this by selecting "mirror image". After loading the mirroring (in case checked) and the pre-rotation angle from the `config.ini` are applied. Then use the rough and fine adjustment to get the image straight aligned (3). If everything is done, you can save the result with "Update Reference Image" (4). -If you have problems with reflections, you can turn the camera in a positions, where the reflection is at a position, where no important information is. To reduce the intensity of the reflection you can also a peace of felt ("Filz") as diffusior at the LED. +If you have problems with reflections, you can turn the camera in a positions, where the reflection is at a position, where no important information is. To reduce the intensity of the reflection you can also a peace of felt ("Filz") as diffusor at the LED. @@ -94,7 +94,7 @@ In order to have a good recognition, the active ROI has two rectangles for align * The outer rectangle is the final size of the ROI -* More important is the inner smaller rectangle. This should tightly fit around the number itself in x- and in y-dimension. Maybe you need to unlock the aspect ratio to change x- and y-size independendly +* More important is the inner smaller rectangle. This should tightly fit around the number itself in x- and in y-dimension. Maybe you need to unlock the aspect ratio to change x- and y-size independently * The line in the middle should go through the middle of the number (in case it is not moving in or out) diff --git a/docs/Hardware-Compatibility.md b/docs/Hardware-Compatibility.md index ec0b320..83cef2c 100644 --- a/docs/Hardware-Compatibility.md +++ b/docs/Hardware-Compatibility.md @@ -1,7 +1,7 @@ # Hardware Compatibility ### General Remark -Altrough a board looks similair, it can have major differences, eg.: +Although a board looks similar, it can have major differences, e.g.: - Processor - Ram (Size! & Type) -> this Project needs at least 4MB RAM! @@ -16,7 +16,7 @@ Altrough a board looks similair, it can have major differences, eg.: This can cause different Power Consumption, Power Requirements, compatibility issues, etc. -Most manufacturers and sellers buy what's cheap today on the Asian markets. In the end, it looks like it is sometimes a trial and error approach which ESP32-CAM Module works reliable. +Most manufacturers and sellers buy what's cheap today on the Asian markets. In the end, it looks like it is sometimes a trial and error approach which ESP32-CAM Module works reliably. Below you find some remarks and experiences from the community: @@ -31,9 +31,9 @@ Below you find some remarks and experiences from the community: There seems to be a lot of "fake" chips, or maybe wrongly configured ESP32 Boards. -For AP MEMORY, all "real" APS**64**04\*3SQR Chips should work. +For AP MEMORY, all "real" APS**64**04\*3SQR chips should work. -For ESP PSRAM, all "real" PSRAM**64**\* should work +For ESP PSRAM, all "real" PSRAM**64**\* should work. 64Mbit density = 8Mbyte PSRAM @@ -72,14 +72,14 @@ The experience with the camera only is based on single modules. It is well possi | Module | Image | Status | | ------------------------------------------------------------ | ----- | ------------------------------ | | ESP32CAM / Different versions on the market!
Especially the PSRAM is sometimes labeled wrong
(Label: 4MB, Real: only 2 MB --> will not work!) | | :heavy_check_mark:
with >=4 MB PSRAM! | -| ESP32-S3-EYE
No Flash LED, pins different used (e.g. LCD diskplay) | | **NOT OKAY** | +| ESP32-S3-EYE
No Flash LED, pins different used (e.g. LCD display) | | **NOT OKAY** | -# SD-Cards +# SD Cards -Due to the limited free available gpios (due to all the extensions needed like: camera, sd-card, LED-flash, ...) the sd card is connected in 1-wire mode. There are some cards, that are compatible with the esp32cam module for unknown reasons. -It is observed, that smaller cards (up to 4 GB) tend to be more stable and larger cards have more problems. But quite some exceptions in the forums (4 GB cards not working, 16 G cards working like a charm). +Due to the limited free available GPIOs (due to all the extensions needed like: camera, SD card, LED-flash, ...) the SD card is connected in 1-wire mode. There are some cards, that are compatible with the esp32cam module for unknown reasons. +It is observed, that smaller cards (up to 4 GB) tend to be more stable and larger cards have more problems. But quite some exceptions in the forums (4 GB cards not working, 16 GB cards working like a charm). # Devices known to work @@ -95,7 +95,7 @@ See [https://github.com/jomjol/AI-on-the-edge-device/discussions/1732](https://g - [https://www.reichelt.de/entwicklerboards-esp32-kamera-2mp-25--debo-cam-esp32-p266036.html?PROVID=2788&gclid=CjwKCAiAqaWdBhAvEiwAGAQlttJnV4azXWDYeaFUuNioMICh-jvxKp6Cifmcep9vvtoT2JRCDqBczRoC7Q0QAvD_BwE](https://www.reichelt.de/entwicklerboards-esp32-kamera-2mp-25--debo-cam-esp32-p266036.html?PROVID=2788&gclid=CjwKCAiAqaWdBhAvEiwAGAQlttJnV4azXWDYeaFUuNioMICh-jvxKp6Cifmcep9vvtoT2JRCDqBczRoC7Q0QAvD_BwE) (27.12.2022) -### SD-Card +### SD Card - Sandisk 2GB Micro SD Class 2 [Sandisk 2GB](https://www.amazon.co.uk/gp/product/B000N3LL02/ref=ppx_yo_dt_b_asin_title_o01_s00?ie=UTF8&psc=1) AITRIP ESP32 and CAM [ESP-32/CAM](https://www.amazon.co.uk/gp/product/B08X49P8P3/ref=ppx_yo_dt_b_asin_title_o03_s00?ie=UTF8&psc=1) diff --git a/docs/Influx-DB.md b/docs/Influx-DB.md index f3b7a18..9888d29 100644 --- a/docs/Influx-DB.md +++ b/docs/Influx-DB.md @@ -1,4 +1,4 @@ # Influx DB -The device also supports direct sending of data to an Influ DB. +The device also supports direct sending of data to an Influx DB. -:bangbang: Only Influx DB 1 is supported! \ No newline at end of file +:bangbang: Only Influx DB 1 is supported! diff --git a/docs/Installation.md b/docs/Installation.md index 3a27b89..550ea99 100644 --- a/docs/Installation.md +++ b/docs/Installation.md @@ -3,7 +3,7 @@ The installation requires multiple steps: 1. Get the right hardware and wire it up 1. Flash the firmware onto the ESP32 -1. Write the data to the SD-Card +1. Write the data to the SD card 1. Start it For point 2 and 3 we provide multiple ways to do it. Pick the one that looks the easiest for you! @@ -11,17 +11,17 @@ For point 2 and 3 we provide multiple ways to do it. Pick the one that looks the ## 1. Hardware ### ESP32-CAM * OV2640 camera module -* Micro SD-Card slot +* Micro SD card slot * 4 or 8 MB PSRAM. It can be easily found on the typical internet stores, searching for ESP32-CAM for less than 10 EUR. -How ever since the hardware is cheap and coming from China, you unluckily could pick a malfunction device. See [Hardware Compatibility](../Hardware-Compatibility) for further advice! +How ever since the hardware is cheap and coming from China, you unluckily could pick a malfunctioning device. See [Hardware Compatibility](../Hardware-Compatibility) for further advice! ### USB->UART interface For first time flashing the firmware a USB -> UART connector is needed. Later firmware upgrades than can be flashed via OTA. ### Power supply -For power supply a 5V source is needed. Most easily this can be done via an USB power supply. The power supply should support minimum 500mA. For buffering current peaks some users reported to use a large elco condensator like a 2200uF between ground and VCC. +For power supply a 5V source is needed. Most easily this can be done via a USB power supply. The power supply should support minimum 500mA. For buffering current peaks some users reported to use a large electrolytic capacitor like a 2200uF between ground and VCC. **:bangbang: Attention:** in several internet forums there are problems reported, in case the ESP32-CAM is only supplied with 3.3V. @@ -44,7 +44,7 @@ A example for wiring can be found here: ![](img/progammer_manual.jpg) -It is also possible to use external LEDs for the illumination instead of the internal flash LED. This is described here: [[External-LED]] +It is also possible to use external LEDs for the illumination instead of the internal flash LED. This is described [here](../External-LED) ## 2. Firmware ### Web Installer @@ -61,7 +61,7 @@ You can access it with the following link: [Web Installer](https://jomjol.github Grab the firmware from the - [Releases page](https://github.com/jomjol/AI-on-the-edge-device/releases) (Stable, tested versions), or the - - [Automatically build development branch](https://github.com/jomjol/AI-on-the-edge-device/actions?query=branch%3Arolling) (experimental, untested versions). Please have a look on [Living on the Edge](../rolling-installation)] first! + - [Automatically build development branch](https://github.com/jomjol/AI-on-the-edge-device/actions?query=branch%3Arolling) (experimental, untested versions). Please have a look on [Living on the Edge](../rolling-installation) first! You need: @@ -75,7 +75,7 @@ Get the [Flash Download Tool](https://www.espressif.com/en/support/download/othe Download and extract the Flash tool, after starting choose "Developer Mode", then "ESP32-DownloadTool" and you are in the setup of the flashing tool. Connect the ESP32-CAM with the USB-UART connection and identify the COM-Port. -:bangbang: **Attention**: if you reflashing the code again, it is strongly recommended to erase the flash memory before flashing the firmware. Especially if you used OTA in between, which might cause remaining information on the flash, to still boot from an old image in the OTA-area, which is not erased by a normal flash. +:bangbang: **Attention**: if you are re-flashing the code again, it is strongly recommended to erase the flash memory before flashing the firmware. Especially if you used OTA in between, which might cause remaining information on the flash, to still boot from an old image in the OTA-area, which is not erased by a normal flash. But your ESP32 in bootloader mode and push start, then it will identify the board and you can configure the bin-configuration according to the following table: @@ -95,50 +95,50 @@ Here you need to install the esptool: ``` pip install esptool ``` -Then connect the ESP32 with the USB-UART connector to the system, put it in bootmode and with the following command you can erase the flash and flash bootloader, partitions and firmware in two steps: +Then connect the ESP32 with the USB-UART connector to the system, put it in boot mode and with the following command you can erase the flash and flash bootloader, partitions and firmware in two steps: ``` esptool erase_flash esptool write_flash 0x01000 bootloader.bin 0x08000 partitions.bin 0x10000 firmware.bin ``` - Maybe you need to specify the COM-port if it is not detected by default. -- If the erase command throws the error `A fatal error occurred: ESP32 ROM does not support function erase_flash.`, your `esptool` might be too old, see https://techoverflow.net/2022/02/08/how-to-fix-esp32-a-fatal-error-occurred-esp32-rom-does-not-support-function-erase_flash/ +- If the erase command throws the error `A fatal error occurred: ESP32 ROM does not support function erase_flash.`, your `esptool` might be too old, see -With some Python installations this may not work and you’ll receive an error, try `python -m pip install esptool` or `pip3 install esptool` +With some Python installations this may not work and you’ll receive an error, try `python -m pip install esptool` or `pip3 install esptool`. -Further recommendations can be found on the [espressif webpage](https://docs.espressif.com/projects/esptool/en/latest/esp32/installation.html) +Further recommendations can be found on the [espressif webpage](https://docs.espressif.com/projects/esptool/en/latest/esp32/installation.html). -## 3. SD-Card -The software expects a SD-Card prepared with certain directory and file structure in order to work properly. -SD-Card most top directory should look like this: +## 3. SD Card +The software expects an SD card prepared with certain directory and file structure in order to work properly. +SD card most top directory should look like this: ![](sd-card-content.png) -This initial setup needs only to be done **once** as further updates (Firmware as well as SD-Card content) are possible with the [Over-The-Air Update](ota.md) mechanism. +This initial setup needs only to be done **once** as further updates (Firmware as well as SD card content) are possible with the [Over-The-Air Update](ota.md) mechanism. #### Notes -- Due to the limited availability of GPIOs (OV2640, Flash-Light, PSRAM & SD-Card) the communication mode to the SD card is limited to 1-line SD-Mode. It showed up, that this results in problems with very large SD-Cards (64GB, sometimes 32 GB) and some no name low cost SD-cards. +- Due to the limited availability of GPIOs (OV2640, Flash-Light, PSRAM & SD card) the communication mode to the SD card is limited to 1-line SD-Mode. It showed up, that this results in problems with very large SD-Cards (64GB, sometimes 32 GB) and some no name low cost SD-cards. - There must be no partition table on the SD-card (no GPT, but only MBR for the single partition) -- Following setting are necessary for formating the SD-card: **SINGLE PARTITION, MBR, FAT32 - 32K. NOT exFAT** +- Following setting are necessary for formatting the SD-card: **SINGLE PARTITION, MBR, FAT32 - 32K. NOT exFAT** - Some ESP32 devices share their SD-card and/or camera GPIOs with the pins for TX and RX. If you see errors like “Failed to connect” then your chip is probably not entering the bootloader properly. Remove the respective modules temporarily to free the GPIOs for flashing. You may find more information about troubleshooting on the [homepage of Espressif](https://docs.espressif.com/projects/esptool/en/latest/esp8266/troubleshooting.html). **The ESP32 indicates problems with the SD card during startup with a fast, endless blinking.** **In this case, please try another SD card.** -### Manual Setup with a SD-Card-Reader on a PC +### Manual Setup with an SD Card Reader on a PC 1. Take the `AI-on-the-edge-device__manual-setup__*.zip` from the [Release](https://github.com/jomjol/AI-on-the-edge-device/releases) page. 1. Open it and extract the `sd-card.zip`. -1. Open it and extract all files onto onto your SD-Card. -1. On the SD-Card, open the `wlan.ini` file and configure it as needed: +1. Open it and extract all files onto onto your SD card. +1. On the SD card, open the `wlan.ini` file and configure it as needed: - Set the corresponding SSID and password - The other parameters are optional - **Note:** The device provides a File Server which can be used to show, edit or delete the files on the SD-Card. For security reasons, the `wlan.ini` file is excluded from this and is hidden from external access to protect the password. + **Note:** The device provides a File Server which can be used to show, edit or delete the files on the SD card. For security reasons, the `wlan.ini` file is excluded from this and is hidden from external access to protect the password. -After this, you can insert the SD-Card into the ESP32 board and start it. +After this, you can insert the SD card into the ESP32 board and start it. ### Remote Setup using the built-in Access Point -On startup of the ESP32, it checks if the `wlan.ini` or the `config/config.ini` are available on the SD-Card. +On startup of the ESP32, it checks if the `wlan.ini` or the `config/config.ini` are available on the SD card. If not, the ESP32 switches to a special mode. In this mode, it provides a Wifi Access Point which can be used to add the missing `wlan.ini` or the `config/config.ini` file. 1. Take the `AI-on-the-edge-device__remote-setup__*.zip` from the [Release](https://github.com/jomjol/AI-on-the-edge-device/releases) page. @@ -148,14 +148,14 @@ If not, the ESP32 switches to a special mode. In this mode, it provides a Wifi A The device has the following fixed IP: [http://192.168.4.1](http://192.168.4.1). -1. Upload initial configuration to sd-card +1. Upload initial configuration to SD card ![](img/setup-config.png) Use the `select file` and `upload` button to start the upload. - A warning will show up if you have choosen a possible wrong file (without default configuration). + A warning will show up if you have chosen a possible wrong file (without default configuration). -1. Store WLAN acces information. +1. Store WLAN access information. After the upload, a new page will be shown: @@ -167,8 +167,8 @@ If not, the ESP32 switches to a special mode. In this mode, it provides a Wifi A **:bangbang: Attention:** - - Carefully check your wifi settings. To change them later on, you need to take out the sd-card and edit the `wlan.ini` manually (or delete it and start again). - - The informations are transfered without encryption! + - Carefully check your wifi settings. To change them later on, you need to take out the SD card and edit the `wlan.ini` manually (or delete it and start again). + - The information is transferred without encryption! Finish the step by pushing `Write wlan.ini` @@ -185,7 +185,7 @@ If not, the ESP32 switches to a special mode. In this mode, it provides a Wifi A ## 4. Initial Startup -After the firmware is flashed and the SD-Card is setup properly, you can start it. +After the firmware is flashed and the SD card is setup properly, you can start it. After power on the connection status is indicated by 3x blinking of the red on board LED. WLAN-Status indication: diff --git a/docs/Integration-Home-Assistant.md b/docs/Integration-Home-Assistant.md index 368b299..b321ed0 100644 --- a/docs/Integration-Home-Assistant.md +++ b/docs/Integration-Home-Assistant.md @@ -1,17 +1,17 @@ # Integration into Home Assistant There are 3 ways to get the data into your Home Assistant: -1. Using MQTT (Automatically Setup Entities using Homeassistant MQTT Discovery) +1. Using MQTT (Automatically Setup Entities using Home Assistant MQTT Discovery) 1. Using MQTT (Manually Setup Entities) 2. Using REST calls The first one is the easier way if you already have MQTT in use. -## Using MQTT (Automatically Setup Entities using Homeassistant MQTT Discovery) +## Using MQTT (Automatically Setup Entities using Home Assistant MQTT Discovery) :bangbang: This feature will be available with the next release! -Starting with Version `>12.0.1`, AI-on-the-edge-devices support Homeassistant Discovery. +Starting with Version `>12.0.1`, AI-on-the-edge-devices support Home Assistant Discovery. 1. Check [here](https://www.home-assistant.io/integrations/mqtt/#mqtt-discovery) to learn more about it and how to enable it in Homeassistant. 1. You also have to enable it in the MQTT settings of your device: @@ -20,7 +20,7 @@ Starting with Version `>12.0.1`, AI-on-the-edge-devices support Homeassistant Di Make sure to select the right Meter Type to get the right units! -On the next start of the device, it will send discovery topics and Homeassistant should pick them up and show them under `Settings > Integrations > MQTT`: +On the next start of the device, it will send discovery topics and Home Assistant should pick them up and show them under `Settings > Integrations > MQTT`: ![grafik](https://user-images.githubusercontent.com/1783586/199352538-ddcc3484-39ef-44f4-a853-53286807d30b.png) ![grafik](https://user-images.githubusercontent.com/1783586/199352565-9b0ade28-cb43-47b4-821f-7909cad41a73.png) @@ -39,7 +39,7 @@ mqtt: unique_id: watermeter_value unit_of_measurement: 'm³' state_class: total_increasing - device_class: water # Needs Homeassistant 2022.11! + device_class: water # Needs Home Assistant 2022.11! icon: 'mdi:water-pump' availability_topic: wasserzaehler/connection payload_available: connected @@ -50,7 +50,7 @@ mqtt: unique_id: watermeter_rate unit_of_measurement: 'm³/min' state_class: measurement - device_class: water # Needs Homeassistant 2022.11! + device_class: water # Needs Home Assistant 2022.11! icon: 'mdi:water-pump' availability_topic: wasserzaehler/connection payload_available: connected @@ -126,7 +126,7 @@ Note that you also can add it using the UI. ![grafik](https://user-images.githubusercontent.com/1783586/193472091-1484aac4-ddc2-48ba-896c-28370963fc2d.png) ### Statistics Graph -Creating Statistics Graphs (eg. usage per day) is easy using the [Energy Dashboard](https://www.home-assistant.io/home-energy-management/): +Creating Statistics Graphs (e.g. usage per day) is easy using the [Energy Dashboard](https://www.home-assistant.io/home-energy-management/): ![grafik](https://user-images.githubusercontent.com/1783586/193471893-d8ab8f5f-0906-4076-8926-8b5a69a24bce.png) Note that there seems to be a bug in the graph, see [https://github.com/home-assistant/frontend/issues/13995](https://github.com/home-assistant/frontend/issues/13995)! @@ -136,7 +136,7 @@ Note that there seems to be a bug in the graph, see [https://github.com/home-ass See also [Influx-DB](../Influx-DB). -If you have setup InfluxDB already, it is also possible to fetch statistics from there, eg. daily usage: +If you have setup InfluxDB already, it is also possible to fetch statistics from there, e.g. daily usage: ``` from(bucket: "HomeAssistant") |> range(start: v.timeRangeStart, stop: v.timeRangeStop) @@ -155,7 +155,7 @@ When using REST, Home Assistant has to periodically call an URL on the ESP32 whi See [REST API](../REST-API) for a list of available URLs. -The most practical one is the `json` entrypoint which provides the most relevant data JSON formated: +The most practical one is the `json` entrypoint which provides the most relevant data JSON formatted: `http:///json` This would return: ```JSON diff --git a/docs/MQTT-API.md b/docs/MQTT-API.md index 8c25b0d..689182f 100644 --- a/docs/MQTT-API.md +++ b/docs/MQTT-API.md @@ -49,7 +49,7 @@ The following parameters have to be defined: * #### Rate * #### Rate_per_time_unit - The time Unit gets set with the Homeassistant Discovery, eg. `h` or `m` (minutes) + The time Unit gets set with the Home Assistant Discovery, e.g. `h` or `m` (minutes) * #### Rate_per_digitalization_round The `interval` defines when the next round gets triggered diff --git a/docs/Neural-Network-Types.md b/docs/Neural-Network-Types.md index 5231733..5e5505a 100644 --- a/docs/Neural-Network-Types.md +++ b/docs/Neural-Network-Types.md @@ -29,7 +29,7 @@ No setting of the type in the firmware is necessary. The type can detect by the Technically a wrong network will work and create output, but that would be totally arbitrary * Not all type of pointers are trained in all networks. * For the 11 classes digits network there many different types of digits trained. The reason is, that you 1) only need 20-30 training images and 2) the data collection is ongoing much longer - * For the continious and 100 classes network especially for the digits, there are only a few types of digits trained up to now + * For the continuous and 100 classes network especially for the digits, there are only a few types of digits trained up to now * Therefore sometimes for the digits it is more effective to choose the simpler 11 classes network type (= default). @@ -63,7 +63,7 @@ Example: `dig-class11_1410_s2_q.tflite` ### Analog Pointer ("ana-cont_XXX.tflite" & "ana-class100_XXX.tflite") -This is to transfer the direction of a pointer into a continuous number between 0 and 1, whereas 0 (=1) is the upwards position (12 o'clock), 0.25 corresponds to the 3 o'clock positions and so on. This network is a envolop for all different types of pointers. Currently there are no dedicated network trainings for specific types of pointers. +This is to transfer the direction of a pointer into a continuous number between 0 and 1, whereas 0 (=1) is the upwards position (12 o'clock), 0.25 corresponds to the 3 o'clock positions and so on. This network is a envelop for all different types of pointers. Currently there are no dedicated network trainings for specific types of pointers. There are two types of network structure, currently both are supported. The "class100" is a pure classification network, that might need a bit more accuracy in the labeling. "cont" is a no classic approach with a continuous output off only 2 neurons (details see below). @@ -77,7 +77,7 @@ There are two types of network structure, currently both are supported. The "cla #### Training data needs * Quadratic images, minimum size: 32x32 pixel -* Typically 100 - 200 images with a resultion of 1/100 of the full rotation (every 0.1 value or 3.6°) +* Typically 100 - 200 images with a resolution of 1/100 of the full rotation (every 0.1 value or 3.6°) * Naming: x.y_ARBITRARY.jpg, where x.y = value 0.0 ... 9.9 #### CNN Technical details: @@ -89,8 +89,8 @@ There are two types of network structure, currently both are supported. The "cla ##### Output * **ana-cont**_XXX.tflite: - * 2 neurons with output in range [-1, 1] - representing a sinus / cosinus encoding of the angle - * needs to be converted to angle with arctan-hyperbolicus function + * 2 neurons with output in range [-1, 1] - representing a sinus / cosine encoding of the angle + * needs to be converted to angle with arctan-hyperbolic function * **ana-class100**_XXX.tflite * 100 neurons representing the classes from 0.0, 0.1, ... 9.8, 9.9 @@ -129,13 +129,13 @@ The digit type is a classical classification network, with 11 classes representi * 11 neurons for image classification (last layer normalized to 1) * Neuron 0 to 9 represent the corresponding numbers "0" to "9" - * Neron 10 represent the "Not-A-Number" class, telling, that the image is not uniquely classified + * Neuron 10 represents the "Not-A-Number" class, telling, that the image is not uniquely classified ### Digits with rolling results ("dig-class100_XXX.tflite" & "dig-cont_XXX.tflite") -This type of network tries to overcome the problem, that there are intermediate values, when a rolling digit is between two numbers. Previous this was the "N" class. In this network type, there are also subdigit values trained, so that the intermediate state can be used as additional information for the algorithms. +This type of network tries to overcome the problem, that there are intermediate values, when a rolling digit is between two numbers. Previous this was the "N" class. In this network type, there are also sub-digit values trained, so that the intermediate state can be used as additional information for the algorithms. #### Types of counters trained: @@ -164,8 +164,7 @@ This type of network tries to overcome the problem, that there are intermediate * **dig-cont**_XXX.tflite: * 10 neurons representing the digits 0, 1, ... 9. The intermediate values are represented by weighted normalized values of two neighboring output neurons - * needs to be converted to angle with arctan-hyperbolicus function + * needs to be converted to angle with arctan-hyperbolic function * **dig-class100**_XXX.tflite * 100 neurons representing the classes from 0.0, 0.1, ... 9.8, 9.9 - diff --git a/docs/New-Releases-Notification.md b/docs/New-Releases-Notification.md index 9bd85ae..2b803bb 100644 --- a/docs/New-Releases-Notification.md +++ b/docs/New-Releases-Notification.md @@ -20,4 +20,4 @@ See also [Github Documentation](https://docs.github.com/en/account-and-profile/m Alternatively or if you do not want to create a Github account, [CodeRelease.io](https://coderelease.io) can be an alternative. -You also have to subscribe with an emailaddress but no account is required. \ No newline at end of file +You also have to subscribe with an email address but no account is required. diff --git a/docs/REST-API.md b/docs/REST-API.md index 9f238b4..5315f3b 100644 --- a/docs/REST-API.md +++ b/docs/REST-API.md @@ -1,7 +1,7 @@ # REST API Various information is directly accessible over specific REST calls. -To use it, just append them to the IP, separated with a `/`, eg. `http://192.168.1.1/json` +To use it, just append them to the IP, separated with a `/`, e.g. `http://192.168.1.1/json` Note: For more detailed information to the REST handler, have a look to the code in the repository: [registered handlers](https://github.com/jomjol/AI-on-the-edge-device/search?q=camuri.uri) @@ -65,7 +65,7 @@ Note: For more detailed information to the REST handler, have a look to the code Show last aligned image * ### img_tmp/alg_roi.jpg - Show last aligned image incuding ROI overlay + Show last aligned image including ROI overlay ## Status * ### statusflow @@ -82,7 +82,7 @@ Note: For more detailed information to the REST handler, have a look to the code * ### sysinfo Show system infos in JSON syntax - - Example: [{"firmware": "","buildtime": "2023-01-25 12:41","gitbranch": "HEAD","gittag": "","gitrevision": "af13c68+","html": "Development-Branch: HEAD (Commit: af13c68+)","cputemp": "64","hostname": "WaterMeterTest","IPv4": "192.168.xxx.xxx","freeHeapMem": "2818330"}] + - Example: `[{"firmware": "","buildtime": "2023-01-25 12:41","gitbranch": "HEAD","gittag": "","gitrevision": "af13c68+","html": "Development-Branch: HEAD (Commit: af13c68+)","cputemp": "64","hostname": "WaterMeterTest","IPv4": "192.168.xxx.xxx","freeHeapMem": "2818330"}]` * ### starttime Show starttime diff --git a/docs/ROI-Configuration.md b/docs/ROI-Configuration.md index bf12f04..e304fbc 100644 --- a/docs/ROI-Configuration.md +++ b/docs/ROI-Configuration.md @@ -24,7 +24,7 @@ In order to use it for reading a meter, the focal-length of the OV2640 camera h **ATTENTION:** this modification will void any warranty, as the sealing of the lens objective is broken! -**ATTENTION:** This modification will render the camera unsuitable for general, web-cam type applications unless the focal length is changed back to the original setting. +**ATTENTION:** This modification will render the camera unsuitable for general, web-cam type applications unless the focal length is changed back to the original setting. ![](img/focus_adjustment.jpg) @@ -79,4 +79,3 @@ Here an example: | ------------ | --------------------------------- | | :heavy_check_mark: **Okay** | dig-class100_OK | | :x: **Not** Okay | dig-class100_NOK | - diff --git a/docs/Testing.md b/docs/Testing.md index bdb3408..3d32f2b 100644 --- a/docs/Testing.md +++ b/docs/Testing.md @@ -34,11 +34,11 @@ Now you can use Visual Studio Code or a standard console to upload the test code image -Alternativ you can run it in console/terminal with `platformio test --environment esp32cam`. +Alternatively you can run it in console/terminal with `platformio test --environment esp32cam`. In my environment the serial terminal not opens. I have to do it for myself. You will see much logging. If any test fails it logs it out. Else it logs all test passed in the end. ## Troubleshooting -If you test very much cases in one function, the device runs in stackoverflow and an endless boot. Reduce the count of test cases or split the test function in multiple functions. +If you test very much cases in one function, the device runs in Stack Overflow and an endless boot. Reduce the count of test cases or split the test function in multiple functions. diff --git a/docs/Upload-files-by-script.md b/docs/Upload-files-by-script.md index 5ed431d..d1f968f 100644 --- a/docs/Upload-files-by-script.md +++ b/docs/Upload-files-by-script.md @@ -1,5 +1,5 @@ # Scripted File Upload -To upload a file eg. using `curl`, you first have to delete it and then upload it: +To upload a file e.g. using `curl`, you first have to delete it and then upload it: ``` curl -d '' http://192.168.1.153/delete/html/index.html curl --data-binary @ota_page.html http://192.168.1.153/upload/html/index.html diff --git a/docs/Watermeter-specific-analog---digital-transition.md b/docs/Watermeter-specific-analog---digital-transition.md index 1dba7c3..28b74bd 100644 --- a/docs/Watermeter-specific-analog---digital-transition.md +++ b/docs/Watermeter-specific-analog---digital-transition.md @@ -1,6 +1,6 @@ -# Analog/Digital Transition on Watermeters +# Analog/Digital Transition on Water Meters -At first, for the most watermeters the default configuration should be work. But the digit, especially the last digit differs in some devices. +At first, for the most water meters the default configuration should be work. But the digit, especially the last digit differs in some devices. ## "Normal" transition @@ -29,4 +29,3 @@ The models for image recognition are good, but have inaccuracies in the range +/ ## How to configure for my meter type If you have a devices with "normal" transition you should not have any issues. On devices with "early" transition, you can set the option `AnalogDigitalTransitionStart` to a value between 6 and 8. - diff --git a/docs/collect-new-images.md b/docs/collect-new-images.md index f878979..48188f0 100644 --- a/docs/collect-new-images.md +++ b/docs/collect-new-images.md @@ -1,7 +1,7 @@ # Collect images to improve the models If your device has new, different digits or pointers it might be that the existing models don't recognize them well. In such case you can collect your images and so we can train the model better. This helps you and also others as the models get more accurate. Adding more images also helps if you have a model that is already known, but the neural models do not produce good results. -Experienced users can do the training also by themself, see [Learn a model with your own images](Learn-models-with-your-own-images.md). +Experienced users can do the training also by themselves, see [Learn a model with your own images](Learn-models-with-your-own-images.md). ## Before you start Before you go ahead, please check if your digits/pointers are not yet contained in the training data. A visual overview is available at [digits](https://jomjol.github.io/neural-network-digital-counter-readout) resp. [pointers](https://jomjol.github.io/neural-network-analog-needle-readout/). @@ -11,27 +11,27 @@ Poor recognition is often caused by blurred images, low contrast or incorrect se ## Collecting images The neural network is trained based on a set of images that have already been collected over time. If your digits are included or at least very similar to included images, the chance is very high that the neural network is working fine for you as well. -The neural network configuration is stored in the TensorFlow Lite format as `*.tfl` or `*.tflite` in the `/config` directory on the SD-Card. A model can be updated (or a new one added) by uploading the new file and activating it on the configuration page or in the config file `/config/config.ini`. +The neural network configuration is stored in the TensorFlow Lite format as `*.tfl` or `*.tflite` in the `/config` directory on the SD card. A model can be updated (or a new one added) by uploading the new file and activating it on the configuration page or in the config file `/config/config.ini`. In order to incorporate new digits a training set of images is required. The training images needs to be collected in the final setup with the help of the `Digits` or `Analog` log settings (not to be confused with the `Data` or `Debug` log). Enable the logging of the images on the configuration page or in the config file `/config/config.ini`: ![](img/enable_log_image.jpg) -Now be patient! You have to wait until it has collected an image of each digit of every type. They wil lbe placed on the SD-Card inthe folder `/log/digit/` resp. `/log/anaolog/`. +Now be patient! You have to wait until it has collected an image of each digit of every type. They wil lbe placed on the SD card in the folder `/log/digit/` resp. `/log/analog/`. After some days, there will be a lot of images, many of them very similar. Because of this, it is important to select only a subset of them for the model training. The tools shown below can help you with that. ## Collecting images for dig-class100/dig-cont/ana-class100 -For digits use [Collectmeterdigits](https://github.com/haverland/collectmeterdigits) resp. for pointers use [collectmeteranalog](https://github.com/haverland/collectmeteranalog) to fetch the images from the device and select a subset of them. Please read the detailed instructions on the mentionded links for details! +For digits use [Collectmeterdigits](https://github.com/haverland/collectmeterdigits) resp. for pointers use [collectmeteranalog](https://github.com/haverland/collectmeteranalog) to fetch the images from the device and select a subset of them. Please read the detailed instructions on the mentioned links for details! If the fetching of the images is too slow for you, a faster way to get the images to your PC is to remove the SD-card from the ESP32 module and insert it into the card reader of yur PC. Then search for two..three images of each digit (**not more! :-)**). You will have to make sure to label the images yourself matching the effective value they are supposed to show. ## Share your images -In most cases we will integrate your images in the training dataset of the models. Only if we fear a degradation of the models or you need a different behaviour, we might not include the data in the standard models (see at bottom of page for reasons). +In most cases we will integrate your images in the training dataset of the models. Only if we fear a degradation of the models or you need a different behavior, we might not include the data in the standard models (see at bottom of page for reasons). To provide your images to us for training the model, open an [Github Issue](https://github.com/jomjol/AI-on-the-edge-device/issues/new/choose) and append the zipped images ito it. diff --git a/docs/index.md b/docs/index.md index 25f9c59..c14b60e 100644 --- a/docs/index.md +++ b/docs/index.md @@ -4,17 +4,17 @@ Welcome to the AI-on-the-edge-device project! This is the documentation. For the source code, please head to [github.com/jomjol/AI-on-the-edge-device](https://github.com/jomjol/AI-on-the-edge-device). -Artificial intelligence based systems have been established in our every days live. Just think of speech or image recognition. Most of the systems relay on either powerful processors or a direct connection to the cloud for doing the calculations up there. With the increasing power of modern processors the AI systems are coming closer to the end user - which is usually called **edge computing**. -Here this edge computing is brought into a practical oriented example, where a AI network is implemented on a ESP32 device so: **AI on the edge**. +Artificial intelligence based systems have been established in our everyday lives. Just think of speech or image recognition. Most of the systems rely on either powerful processors or a direct connection to the cloud for doing the calculations up there. With the increasing power of modern processors the AI systems are coming closer to the end user - which is usually called **edge computing**. +Here this edge computing is brought into a practice-oriented example, where a AI network is implemented on a ESP32 device so: **AI on the edge**. ## Key features - Tensorflow Lite (TFlite) integration - including easy to use wrapper -- Inline Image processing (feature detection, alignment, ROI extraction) +- Inline image processing (feature detection, alignment, ROI extraction) - **Small** and **cheap** device (3x4.5x2 cm³, < 10 EUR) -- camera and illumination integrated +- Camera and illumination integrated - Web surface to administrate and control - OTA-Interface to update directly through the web interface -- Full integration into Homeassistant +- Full integration into Home Assistant - Support for Influx DB 1 - MQTT - REST API @@ -44,10 +44,10 @@ Here this edge computing is brought into a practical oriented example, where a A This is about image recognition and digitalization, done totally on a cheap ESP32 board using artificial intelligence in form of convolutional neural networks (CNN). Everything, from image capture (OV2640), image preprocessing (auto alignment, ROI identification) all the way down to the image recognition (CNN structure) and result plausibility is done on a cheap 10 EUR device. -This all is integrated in an easy to do setup and use environment, taking care for all the background processing and handling, including regular job scheduler. The user interface is an integrated web server, that can be easily adjusted an offers the data as an API in different options. +This all is integrated in an easy to do setup and use environment, taking care for all the background processing and handling, including regular job scheduler. The user interface is an integrated web server, that can be easily adjusted and offers the data as an API in different options. -The task to be demonstrated here is a automated readout of an analog water meter. The water consumption is to be recorded within a house automatization and the water meter is totally analog without any electronic interface. Therefore the task is solved by taking regularly an image of the water meter and digitize the reading. +The task to be demonstrated here is an automated readout of an analog water meter. The water consumption is to be recorded within a house automatization and the water meter is totally analog without any electronic interface. Therefore, the task is solved by regularly taking an image of the water meter and digitizing the reading. There are two types of CNN implemented, a classification network for reading the digital numbers and a single output network for digitalize the analog pointers for the sub digit readings. -This project is a evolution of the [water-meter-system-complete](https://github.com/jomjol/water-meter-system-complete), which uses ESP32-CAM just for taking the image and a 1GB-Docker image to run the neural networks backbone. Here everything is integrated in an ESP32-CAM module with 8MB of RAM and a SD-Card as data storage. +This project is an evolution of the [water-meter-system-complete](https://github.com/jomjol/water-meter-system-complete), which uses ESP32-CAM just for taking the image and a 1GB-Docker image to run the neural network's backbone. Here everything is integrated in an ESP32-CAM module with 8MB of RAM and a SD card as data storage. diff --git a/docs/initial-setup.md b/docs/initial-setup.md index 18b9e61..339d7fc 100644 --- a/docs/initial-setup.md +++ b/docs/initial-setup.md @@ -1,6 +1,6 @@ # Initial Setup -After setting up the device (firmware, sd-card, wlan) the device will connect to the wifi access point and start in an initial setup configuration: +After setting up the device (firmware, SD card, WLAN) the device will connect to the wifi access point and start in an initial setup configuration: ![](img/setup_initial_welcome.png){: style="width:500px"} @@ -26,7 +26,7 @@ Ensure an **exact horizontal alignment** of the number via the alignment / refer | --------------------------- | ------------------------------- | | ![](img/alignment_okay.jpg) | ![](img/alignment_not_okay.jpg) | -**:bangbang: Attention:** Updating the reference image, also means, that all alignment images and ROIs needs to be teached again. Therefore do this step later only with caution. +**:bangbang: Attention:** Updating the reference image, also means, that all alignment images and ROIs needs to be taught again. Therefore do this step later only with caution. If everything is done, you can save the result with "Update Reference Image" (4). Please do not reboot at this stage, but go to the next section. @@ -58,11 +58,11 @@ First of all, if you don't have that kind of numbers on you meter, you can disab In contrast to the reference images, here there are more ROIs possible. You can switch between them with the drop down box (2). If you need additional ROIs or delete them you can do this with the control at (2). -**Attention:** The order of the ROIs defines, how the indiviual digits are combined to the total number. The first ROI is the digit with the highest order, then the second and so on. You can control the order in the selector tab and change it with the buttons "move Next" or "move Previous". +**Attention:** The order of the ROIs defines, how the individual digits are combined to the total number. The first ROI is the digit with the highest order, then the second and so on. You can control the order in the selector tab and change it with the buttons "move Next" or "move Previous". As for the reference images you can change position, size and name of the ROI in the text fields or define them via drag and drop through the mouse button. -In most cases the digits are ordered in a aequidistant order and have the same size, you can synchronize them with the control in (4). +In most cases the digits are ordered in a equidistantly and have the same size, you can synchronize them with the control in (4). Don' t forget to save the settings with "Save" and do not reboot at this stage. @@ -82,10 +82,14 @@ Here is an example with the details for the ROI "ana1": For the digital meters it is a little bit more complicated, as there are different options of digital models, that you can choose. 1. Digital meter, that only recognized full digits (0, 1, 2, 3, ... 9) - Naming: `dig-class11-....tfl` + **Advantage:** broad variety of types included in the training + **Disadvantage:** partially rotated numbers cannot be detected -2. Model with subdigit resulition (0.0, 0.1, 0.2, .... 9.8, 9.9) - Naming: `dig-cont-....tfl` or `dig-class100-....tfl` +2. Model with sub-digit resolution (0.0, 0.1, 0.2, .... 9.8, 9.9) - Naming: `dig-cont-....tfl` or `dig-class100-....tfl` + **Advantage:** partial numbers can be detected and a better post processing is possible + **Disadvantage:** only limited types of meter types are trained due to the high effort for the training data Details and the corresponding "perfect" setting is explained here: [Details ROI Configuration](https://jomjol.github.io/AI-on-the-edge-device-docs/ROI-Configuration/) @@ -118,7 +122,7 @@ The configuration is divided into different sub topics: * PostProcessing * MQTT * InfluxDB -* GPIOSettings +* GPIO Settings * Autotimer * DataLogging * Debug @@ -131,9 +135,9 @@ The setting itself is done in the next column (2) and a brief explanation you ca Don' t forget to save the settings with "Save" and do not reboot at this stage. -#### Expert Modus +#### Expert Mode -With the normal parameters you should be able to make the needed settings for most of the system. Sometimes there is some fine tunning needed. For this there is an expert modus available. This can be enabled with the check box at the top (4). After this you see much more parameters. But before modifiying them you should be really sure, what they are about. +With the normal parameters you should be able to make the needed settings for most of the system. Sometimes there is some fine tunning needed. For this there is an expert mode available. This can be enabled with the check box at the top (4). After this you see much more parameters. But before modifying them you should be really sure, what they are about. @@ -143,13 +147,13 @@ After setting up everything, there is a last step to be done: ![](img/initial_setup_6_finish_reboot.jpg){: style="width:500px"} -With (1) you leave the setup modus and reboot to normal operation mode. +With (1) you leave the setup mode and reboot to normal operation mode. ## Access to setup in normal operation mode -You can access all the settings also during the normal working mode via the "Settings" menue: +You can access all the settings also during the normal working mode via the "Settings" menu: ![](img/initial_setup_7_access_normal_mode.jpg){: style="width:500px"} diff --git a/docs/nav.yml b/docs/nav.yml index 44bc08b..4cb1812 100644 --- a/docs/nav.yml +++ b/docs/nav.yml @@ -60,7 +60,7 @@ nav: - outdated--Gasmeter-Log-Downloader.md - outdated--Migrate-Old-Config-To-New-Config.md - - Asorted Pages: + - Assorted Pages: # List all pages which are not covered by above list # Step by step we should migrate those page to the above list - ... diff --git a/docs/outdated--Gasmeter-Log-Downloader.md b/docs/outdated--Gasmeter-Log-Downloader.md index b06b76b..3cf21b4 100644 --- a/docs/outdated--Gasmeter-Log-Downloader.md +++ b/docs/outdated--Gasmeter-Log-Downloader.md @@ -1,23 +1,23 @@ -# Gasmeter Log-Downloader +# Gas Meter Log Downloader !!! Warning This page no longer is maintained! -This small tool downloads the logfiles from your ESP32 and stores the last value of the day in an *.csv file. +This small tool downloads the log files from your ESP32 and stores the last value of the day in an *.csv file. -To use this tool you need to **activate the debug logfile** in your configuration (Configuration / Debug / Logfile). I go with 30 days of retention in days. +To use this tool you need to **activate the debug log files** in your configuration (Configuration / Debug / Logfile). I go with 30 days of retention in days. -It downloads only the past logfiles (yesterday and older). +It downloads only the past log files (yesterday and older). -You can define the max. number of Logfiles to download (beginning from newest [yesterday]). +You can define the max. number of log files to download (beginning from newest [yesterday]). I wrote this tool to get a chart of the daily gas consumption to optimize my gas powered heating. **Variables to define by yourself:** -- **URL to Logfile-Path on Device:** "http://ESP32-IP-Address/fileserver/log/message/" -- **Download Logfiles to:** enter a valid directory, e.g. "D:\Gaszaehler\Auswertung\Log-Downloads\" +- **URL to Log file-Path on Device:** "http://ESP32-IP-Address/fileserver/log/message/" +- **Download Log files to:** enter a valid directory, e.g. "D:\Gaszaehler\Auswertung\Log-Downloads\" - **Output CSV-File:** enter a valid directory, e.g. "D:\Gaszaehler\Auswertung\DailyValues.csv" -- **Download Logfiles from past # days:** enter the max. number of logfiles you want to download (<= your logfile retention value in your device configuration) +- **Download Log files from past # days:** enter the max. number of log files you want to download (<= your log files retention value in your device configuration) -Feel free to optimize and modify it. \ No newline at end of file +Feel free to optimize and modify it. diff --git a/docs/outdated--Migrate-Old-Config-To-New-Config.md b/docs/outdated--Migrate-Old-Config-To-New-Config.md index e831391..8d3f699 100644 --- a/docs/outdated--Migrate-Old-Config-To-New-Config.md +++ b/docs/outdated--Migrate-Old-Config-To-New-Config.md @@ -7,7 +7,7 @@ There are only some few steps necessary to migrate your old system to the new on Please follow the following steps: -#### 1. Follow the installation guide to flash the ESP32CAM and prepare a SD-Card with the content of the master +#### 1. Follow the installation guide to flash the ESP32CAM and prepare a SD Card with the content of the master #### 2. Save the following files from the old Docker system on your PC: @@ -128,4 +128,4 @@ ImageSize = VGA #### 11. Restart the system. -#### 12. After the first start set manually the PreValue in the new system \ No newline at end of file +#### 12. After the first start set manually the PreValue in the new system