diff --git a/docs/config-manager.md b/docs/config-manager.md index a789ad8..cbdc8bd 100644 --- a/docs/config-manager.md +++ b/docs/config-manager.md @@ -1,5 +1,6 @@ # Configuration Manager -For whatever function a device with an ESP8266 might have, it could be that you want the user to change some settings or parameters, such as the speed of a motor, or the color of a LED. The configuration manager provides a method to modify parameters from the broswer which will be accessible from the software application. The parameters are generated from a JSON file. The configuration manager stores a struct with configuration data in the EEPROM. Structure can be changed at build time, data can be changed at runtime through the GUI which is also auto generated from the JSON. + +For whatever function a device with an ESP8266 might have, it could be that you want the user to change some settings or parameters, such as the speed of a motor, or the color of a LED. The configuration manager provides a method to modify parameters from the browser which will be accessible from the software application. The parameters are generated from a JSON file. The configuration manager stores a struct with configuration data in the EEPROM. Structure can be changed at build time, data can be changed at runtime through the GUI which is also auto generated from the JSON. Usage of this class is easy. See below how to define your configuration parameters. Once you have done this, these can be changed from the browser, and simply be called in the rest of your application as `configManager.data.parameterName`. @@ -33,7 +34,7 @@ This method resets the EEPROM contents to the default values. ```c++ configData data; ``` -This member is the structure containing the RAM mirror of the configuration data. +This member is the structure containing the RAM mirror of the configuration data. ## Note on partial updates @@ -47,7 +48,7 @@ On the low level then the full block will be rewritten. The reason for this impl ## Updating from the C++ code -Of course you can also update configuration information from your code rather than through the web interface. To do this you need to make a RAM mirror of the `configManager.data` object. After you have modified the content of this object, you can simply give a pointer to its contents as an argument to the `configManager.saveRaw` function to store the result in EEPROM. +Of course you can also update configuration information from your code rather than through the web interface. To do this you need to make a RAM mirror of the `configManager.data` object. After you have modified the content of this object, you can simply give a pointer to its contents as an argument to the `configManager.saveRaw` function to store the result in EEPROM. ## Code Generation @@ -70,7 +71,7 @@ As mentioned earlier, the configuration data is defined in the JSON file `html/j "name": "dummyBool", "type": "bool", "value": "true" - }, + }, { "name": "dummyFloat", "type": "float", @@ -79,7 +80,7 @@ As mentioned earlier, the configuration data is defined in the JSON file `html/j ] ``` -Supported data types are: bool, uint8_t, int8_t, uint16_t, int16_t, uint32_t, int32_t, float and char. The length argument is mandatory for datatype char to indicate the length of the string. Variable length strings are not supported. Also, arrays are not supported for now. For this example, the pre-build python script `preBuildConfig.py` will generate the following two files. These should be fairly self explanatory and show how the JSON file is translated into a C struct. +Supported data types are: bool, uint8_t, int8_t, uint16_t, int16_t, uint32_t, int32_t, float and char. The length argument is mandatory for datatype char to indicate the length of the string. Variable length strings are not supported. Also, arrays are not supported for now. For this example, the pre-build python script `preBuildConfig.py` will generate the following two files. These should be fairly self explanatory and show how the JSON file is translated into a C struct. The `configVersion` is the CRC32 hash of the JSON file. This is added to the C code in order to detect if the JSON has changed compared to the content of the EEPROM, since the `configVersion` will also be stored in the EEPROM. This means that if a field is changed in the JSON, the application will know to reject the current content of the EEPROM since it might not be in accordance to the struct definitions it knows. diff --git a/docs/fetch.md b/docs/fetch.md index 83799d2..d266af8 100644 --- a/docs/fetch.md +++ b/docs/fetch.md @@ -2,7 +2,7 @@ Fetching or posting data to the internet is one of the core tasks of an IoT device. Doing so over HTTP is implemented quite well in the default ESP8266 Arduino libraries, but for HTTPS requests things are less straightforward. This class implements arbitrary HTTPS requests in a secure way, without requiring any specific certificates or fingerprints to be hard coded in the application. A full certificate store is automatically downloaded on build, and stored in PROGMEM. ## Class Methods - + #### begin ```c++ @@ -70,7 +70,7 @@ while (fetch.busy()) { if (fetch.available()) { - Serial.write(fetch.read()); + Serial.write(fetch.read()); } } @@ -82,20 +82,20 @@ For reading in a shorter response you can simply use `readString()` instead: ```c++ fetch.GET("https://www.google.com"); -Serial.write(fetch.readString()); +Serial.write(fetch.readString()); fetch.clean(); ``` ## Code Generation -As mentioned earlier a full certificate store is saved in PROGMEM as part of the application. By default this store is located in `certificates.h`, and will be included in the build. These certificates will be used by the ESP8266 Arduino BearSSL class to establish a secure connection. +As mentioned earlier a full certificate store is saved in PROGMEM as part of the application. By default this store is located in `certificates.h`, and will be included in the build. These certificates will be used by the ESP8266 Arduino BearSSL class to establish a secure connection. If you ever want to update or rebuild the certificate store, you can do this by enabling or running the pre-build script `preBuildCertificates.py`. This script will read in all root certificates from the Mozilla certificate store and process these into a format that is compatible with the ESP8266 Arduino layer. -For this step OpenSSL is needed. On Linux this is probably availble by default, on Windows this comes as part of something like MinGW, or Cygwin, but is also installed with the Windows Git client. If needed you can edit the path to OpenSSL at the top of the `preBuildCertificates.py` file: +For this step OpenSSL is needed. On Linux this is probably available by default, on Windows this comes as part of something like MinGW, or Cygwin, but is also installed with the Windows Git client. If needed you can edit the path to OpenSSL at the top of the `preBuildCertificates.py` file: ```c++ #path to openssl -openssl = "C:\\msys32\\usr\\bin\\openssl" +openssl = "C:\\msys32\\usr\\bin\\openssl" ``` diff --git a/docs/getting-started.md b/docs/getting-started.md index 6a5dc76..dc82ad4 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -1,6 +1,6 @@ # Getting Started -This section will describe how to use the framework, and what prerequisites are needed. To get started read below how you should build the framework. When you can build successfully you can simply start adding your own code in `main.c` which contains the familiar `setup()` and `loop()` functions. +This section will describe how to use the framework, and what prerequisites are needed. To get started read below how you should build the framework. When you can build successfully you can simply start adding your own code in `main.c` which contains the familiar `setup()` and `loop()` functions. ## Building the Framework @@ -9,10 +9,10 @@ To use this framework as is, it is recommended to use PlatformIO to build from s ``` build/preBuildHTML.py build/preBuildConfig.py -build/preBuildCertificates.py +build/preBuildCertificates.py ``` -You can choose to comment these scripts, since all default artefacts generated by these are committed in this GitHub repo, so that these pre-build steps are optional. +You can choose to comment these scripts, since all default artifacts generated by these are committed in this GitHub repo, so that these pre-build steps are optional. **preBuildHTML.py:** This pre-build step will re-generate the web interface to `html.h` by simply calling `npm run build`. Read more details [here](https://github.com/maakbaas/esp8266-iot-framework/blob/master/docs/getting-started.md#editing-the-web-interface). @@ -20,11 +20,11 @@ You can choose to comment these scripts, since all default artefacts generated b **preBuildCertificates.py:** This build step generates `certificates.h` containing a full root certificate store to enable arbitrary HTTPS requests with the ESP8266. More info on this process can be found [here](https://github.com/maakbaas/esp8266-iot-framework/blob/master/docs/fetch.md). -For this step OpenSSL is needed. On Linux this is probably availble by default, on Windows this comes as part of something like MinGW, or Cygwin, but is also installed with the Windows Git client. If needed you can edit the path to OpenSSL at the top of the file: +For this step OpenSSL is needed. On Linux this is probably available by default, on Windows this comes as part of something like MinGW, or Cygwin, but is also installed with the Windows Git client. If needed you can edit the path to OpenSSL at the top of the file: ```python #path to openssl -openssl = "C:\\msys32\\usr\\bin\\openssl" +openssl = "C:\\msys32\\usr\\bin\\openssl" ``` ## Minimal main.c @@ -45,7 +45,7 @@ Of course if you do not want to use certain parts of the framework you can remov #include "fetch.h" #include "configManager.h" -void setup() +void setup() { Serial.begin(115200); @@ -56,7 +56,7 @@ void setup() fetch.begin(); } -void loop() +void loop() { //software interrupts WiFiManager.loop(); diff --git a/docs/web-server.md b/docs/web-server.md index a9d6b53..8fb1c07 100644 --- a/docs/web-server.md +++ b/docs/web-server.md @@ -10,9 +10,9 @@ The web server is based on ESPAsyncWebServer and presents the web interface whic void begin(); ``` -The web server has only one public method. Call this method in your setup fuction to initialize and start the web server. +The web server has only one public method. Call this method in your setup function to initialize and start the web server. -## Web Server +## Web Server The basic setup of the webserver is done with three simple rules, which are described below. @@ -32,7 +32,7 @@ With a POST request to this URL you can upload a file to the SPIFFS filesystem #### onNotFound -For all requested URL's that do not exist (this includes the root URL), the web interface will be loaded and served to the user. This web interface is served from a PROGMEM byte array which is generated with Webpack during the NPM build process. +For all requested URL's that do not exist (this includes the root URL), the web interface will be loaded and served to the user. This web interface is served from a PROGMEM byte array which is generated with Webpack during the NPM build process. ## API Implementation