IotWebConf Documentation

IotWebConf operates based on the current WiFi availability:

1. AP Mode (Access Point): Triggered when no WiFi is configured or the configured network is unavailable. The device creates its own AP (typically at 192.168.4.1). Clients can connect to this AP to access the web interface and configure settings.
2. WiFi Mode: Once configured, the device attempts to connect to the specified network.
3. Fallback: If multiple WiFi connections are defined, the device will automatically try the next one if the previous one is unavailable.
4. Runtime Access: Even after connecting to WiFi, the config portal remains available. To access it via the local network, use the username admin and the password configured for the AP password.

To control the visibility of settings in the configuration portal, use these two group types:

1. OptionalParameterGroup: The group's fieldset can be hidden (inactive) or shown (active). This is useful for non-mandatory settings that should only be revealed when requested.
2. ChainedParameterGroup: Groups are linked sequentially. A subsequent group in the chain only becomes visible after the preceding group item has been interacted with/added.

See examples IotWebConf13OptionalGroup and IotWebConf14GroupChain for implementation details.

Typed parameters (experimental) allow storing data in native formats (e.g., an 8-bit integer stored in one byte of EEPROM) without requiring a valueBuffer. This implementation uses C++ templates and a Builder pattern.

Warning: This interface is experimental and subject to change. See example IotWebConf03TypedParameters for usage.

The IotWebConfSeparator has been removed in v3.0.0. To create field sets or logical groupings in the web interface, you must now use iotwebconf::ParameterGroup.

To use groups:

1. Create an instance of iotwebconf::ParameterGroup.
2. Add parameters to the group using group.addItem(&parameter).
3. Register the group with the main instance using iotWebConf.addParameterGroup(&group).

iotwebconf::ParameterGroup group1("group1", "");
iotwebconf::NumberParameter intParam("Int param", "intParam", intParamValue, NUMBER_LEN, "20", "1..100", "min='1' max='100' step='1'");

// Setup
group1.addItem(&intParam);
iotWebConf.addParameterGroup(&group1);

In v3.0.0, the meaning of defaultValue has changed. It is no longer used to populate the web interface when no value is specified. Instead, defaultValue is automatically assigned to the parameter only the very first time the configuration is loaded.

Important: Do not manually set values inside the if (!validConfig) block after iotWebConf.init(). Instead, rely on the defaultValue provided in the parameter constructor.

AP Mode Security

When connecting in AP mode, communication is protected by the WiFi encryption layer (WPA/WPA2) provided by the chipset.

WiFi Mode (Router) Security

Warning: When accessing the config portal through a WiFi router (WiFi mode), communication is sent over unencrypted HTTP. This means your communication is not hidden from other devices on the same network. To mitigate this, either ensure no untrusted devices are on your network or use the device primarily in AP mode.

Debugging and Passwords

By default, passwords are not shown in the serial debug output. If you need to see passwords in the logs for debugging, you must manually enable visibility in IotWebConf.h by defining: IOTWEBCONF_DEBUG_PWD_TO_SERIAL

Once the device is successfully connected to your WiFi network, the temporary Access Point is disabled. To access the configuration page again via your local network:

1. Find the IP: Determine the device's IP address (e.g., via your WiFi router's client list).
2. Login: Navigate to the device's IP in a web browser. A login page will appear.
3. Credentials:
   • Username: admin
   • Password: The value you previously set for AP password.

Security Warning: The device does not support secure Web connections (HTTPS). Traffic sent over your WiFi network to the configuration page is unencrypted and can be monitored by others on the same network.

When a device is powered on for the first time, it automatically enters Access Point (AP) mode to allow configuration.

1. Detect Network: Look for a WiFi network named testThing on your smartphone or computer.
2. Connect: Connect to the network using the default password smrtThng8266.
3. Configure: Once connected, a configuration page should automatically pop up in your web browser. If not, navigate to the device's IP or local address.

Note: Even without configuration, the device is ready to use with factory defaults in an offline manner.

By default, JSON support is disabled in IotWebConf to save resources. To enable the ability to load configuration parameters from a JSON file on the flash filesystem, you must define the IOTWEBCONF_ENABLE_JSON compile-time directive.

If you are using PlatformIO, add the following flag to your platformio.ini file:

build_flags = -DIOTWEBCONF_ENABLE_JSON

To create a custom parameter type, inherit from the iotwebconf::Parameter C++ class. You can use existing classes like PasswordProperty as templates.

Custom properties are useful for:

• Creating unique HTML form items.
• Changing parameter handling behavior by overriding storeValue() and loadValue() (e.g., to convert internal data formats).