Homie for ESP8266

The Homie for ESP8266 documentation

Welcome to the Homie for ESP8266 documentation. You'll find comprehensive guides and documentation to help you start working with Homie for ESP8266 as quickly as possible. Let's jump right in!

Get Started    

Custom settings

Homie for ESP8266 lets you implement custom settings that can be set from the JSON configuration file and the Configuration API. Below is an example of how to use this feature:

HomieSetting<long> percentageSetting("percentage", "A simple percentage");  // id, description

void setup() {
  percentageSetting.setDefaultValue(50).setValidator([] (long candidate) {
    return (candidate >= 0) && (candidate <= 100);
  });

  Homie.setup();
}

An HomieSetting instance can be of the following types:

Type
Value

bool

true or false

long

An integer from -2,147,483,648 to 2,147,483,647

double

A floating number that can fit into a real64_t

const char*

"Any string"

By default, a setting is mandatory (you have to set it in the configuration file). If you give it a default value with setDefaultValue(), the setting becomes optional. You can validate a setting by giving a validator function to setValidator(). To get the setting from your code, use get(). To get whether the value returned is the optional one or the one provided, use wasProvided().

For this example, if you want to provide the percentage setting, you will have to put in your configuration file:

{
  "settings": {
    "percentage": 75
  }
}

See the CustomSettings example for a concrete use case.

Custom settings