Skip to content
This repository was archived by the owner on Feb 8, 2024. It is now read-only.
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 6 additions & 5 deletions docs/config-manager.md
Original file line number Diff line number Diff line change
@@ -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`.

Expand Down Expand Up @@ -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

Expand All @@ -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

Expand All @@ -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",
Expand All @@ -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.

Expand Down
12 changes: 6 additions & 6 deletions docs/fetch.md
Original file line number Diff line number Diff line change
Expand Up @@ -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++
Expand Down Expand Up @@ -70,7 +70,7 @@ while (fetch.busy())
{
if (fetch.available())
{
Serial.write(fetch.read());
Serial.write(fetch.read());
}
}

Expand All @@ -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"
```
14 changes: 7 additions & 7 deletions docs/getting-started.md
Original file line number Diff line number Diff line change
@@ -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

Expand All @@ -9,22 +9,22 @@ 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).

**preBuildConfig.py:** This build step generates the `config.c` and `config.h` files for the configuration manager based on `html/js/configuration.js` as described in more detail [here](https://github.com/maakbaas/esp8266-iot-framework/blob/master/docs/config-manager.md).

**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
Expand All @@ -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);

Expand All @@ -56,7 +56,7 @@ void setup()
fetch.begin();
}

void loop()
void loop()
{
//software interrupts
WiFiManager.loop();
Expand Down
6 changes: 3 additions & 3 deletions docs/web-server.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand All @@ -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

Expand Down