Allow features to be disabled at build time (#143)
* Add framework for built-time feature selection
* Allow MQTT, NTP, OTA features to be disabled at build time
* Allow Project screens to be disabled at build time
* Allow security features to be disabled at build time
* Switch to std::function for StatefulService function aliases for greater flexibility
* Bump various UI lib versions
* Update docs
A simple, secure and extensible framework for IoT projects built on ESP8266/ESP32 platforms with responsive React front-end.
A simple, secure and extensible framework for IoT projects built on ESP8266/ESP32 platforms with responsive [React](https://reactjs.org/) front-end built with [Material-UI](https://material-ui.com/).
Designed to work with the PlatformIO IDE with [limited setup](#getting-started). Please read below for setup, build and upload instructions.
@ -19,9 +19,7 @@ Provides many of the features required for IoT projects:
* Remote Firmware Updates - Enable secured OTA updates
* Security - Protected RESTful endpoints and a secured user interface
The back end is provided by a set of RESTful endpoints and the responsive React based front end is built using [Material-UI](https://material-ui.com/).
The front end has the prerequisite manifest file and icon, so it can be added to the home screen of a mobile device if required.
Features may be [enabled or disabled](#selecting-features) as required at compile time.
The `REACT_APP_HTTP_ROOT` and `REACT_APP_WEB_SOCKET_ROOT` properties can be modified to point a ESP device running the back end firmware.
The `REACT_APP_HTTP_ROOT` and `REACT_APP_WEB_SOCKET_ROOT` properties can be modified to point a ESP device running the back end.
> **Tip**: You must restart the development server for changes to the environment file to come into effect.
@ -152,9 +150,31 @@ You can enable CORS on the back end by uncommenting the -D ENABLE_CORS build fla
-D CORS_ORIGIN=\"http://localhost:3000\"
```
## Selecting features
Many of the framework's built in features may be enabled or disabled as required at compile time. This can help save sketch space and memory if your project does not require the full suite of features. The access point and WiFi management features are "core features" and are always enabled. Feature selection may be controlled with the build flags defined in [features.ini](features.ini).
Customize the settings as you see fit. A value of 0 will disable the specified feature:
FT_PROJECT | Controls whether the "project" section of the UI is enabled. Disable this if you don't intend to have your own screens in the UI.
FT_SECURITY | Controls whether the [security features](#security-features) are enabled. Disabling this means you won't need to authenticate to access the device and all authentication predicates will be bypassed.
FT_MQTT | Controls whether the MQTT features are enabled. Disable this if your project does not require MQTT support.
FT_NTP | Controls whether network time protocol synchronization features are enabled. Disable this if your project does not require accurate time.
FT_OTA | Controls whether OTA update support is enabled. Disable this if you won't be using the remote update feature.
## Factory settings
The firmware has built-in factory settings which act as default values for the various configurable services where settings are not saved on the file system. These settings can be overridden using the build flags defined in [factory_settings.ini](factory_settings.ini).
The framework has built-in factory settings which act as default values for the various configurable services where settings are not saved on the file system. These settings can be overridden using the build flags defined in [factory_settings.ini](factory_settings.ini).
Customize the settings as you see fit, for example you might configure your home WiFi network as the factory default:
@ -193,7 +213,7 @@ Changing factory time zone setting is a common requirement. This requires a litt
### Device ID factory defaults
If not overridden with a build flag, the firmware will use the device ID to generate factory defaults for settings such as the JWT secret and MQTT client ID.
If not overridden with a build flag, the framework will use the device ID to generate factory defaults for settings such as the JWT secret and MQTT client ID.
> **Tip**: Random values are generally better defaults for these settings, so it is recommended you leave these flags undefined.
@ -481,7 +501,7 @@ class LightStateService : public StatefulService<LightState> {
};
```
Endpoint security is provided by authentication predicates which are [documented below](#security-features). The SecurityManager and authentication predicate may be provided if a secure endpoint is required. The demo project shows how endpoints can be secured.
Endpoint security is provided by authentication predicates which are [documented below](#security-features). The SecurityManager and authentication predicate may be provided if a secure endpoint is required. The placeholder project shows how endpoints can be secured.
#### Persistence
@ -519,7 +539,7 @@ class LightStateService : public StatefulService<LightState> {
};
```
WebSocket security is provided by authentication predicates which are [documented below](#security-features). The SecurityManager and authentication predicate may be provided if a secure WebSocket is required. The demo project shows how WebSockets can be secured.
WebSocket security is provided by authentication predicates which are [documented below](#security-features). The SecurityManager and authentication predicate may be provided if a secure WebSocket is required. The placeholder project shows how WebSockets can be secured.
rjwats
4 years ago
GitHub