

Advanced usage¶

Built-in LED¶

By default, Homie for ESP8266 will blink the built-in LED to indicate its status. However, on some boards like the ESP-01, the built-in LED is actually the TX port, so it is fine if Serial is not enabled, but if you enable Serial, this is a problem. You can easily disable the built-in LED blinking.

void setup() {
  Homie.enableBuiltInLedIndicator(false); // before Homie.setup()
  // ...
}

You may, instead of completely disable the LED control, set a new LED to control:

void setup() {
  Homie.setLedPin(16, HIGH); // before Homie.setup() -- 2nd param is the state when the LED is on
  // ...
}

Change the brand¶

By default, Homie for ESP8266 will spawn a Homie-XXXXXXXX AP, will connect to the MQTT broker with the Homie-XXXXXXXX client ID, etc. You might want to change the Homie text:

void setup() {
  Homie.setBrand("MyIoTSystem"); // before Homie.setup()
  // ...
}

Hook to Homie events¶

You may want to hook to Homie events. Maybe you will want to blink a LED if the Wi-Fi connection is lost, or execute some code prior to a device reset to clear some EEPROM you're using.

void onHomieEvent(HomieEvent event) {
  switch(event) {
    case HOMIE_CONFIGURATION_MODE:
      // Do whatever you want when configuration mode is started
      break;
    case HOMIE_NORMAL_MODE:
      // Do whatever you want when normal mode is started
      break;
    case HOMIE_OTA_MODE:
      // Do whatever you want when OTA mode is started
      break;
    case HOMIE_ABOUT_TO_RESET:
      // Do whatever you want when the device is about to reset
      break;
    case HOMIE_WIFI_CONNECTED:
      // Do whatever you want when Wi-Fi is connected in normal mode
      break;
    case HOMIE_WIFI_DISCONNECTED:
      // Do whatever you want when Wi-Fi is disconnected in normal mode
      break;
    case HOMIE_MQTT_CONNECTED:
      // Do whatever you want when MQTT is connected in normal mode
      break;
    case HOMIE_MQTT_DISCONNECTED:
      // Do whatever you want when MQTT is disconnected in normal mode
      break;
  }
}

void setup() {
  Homie.onEvent(onHomieEvent); // before Homie.setup()
  // ...
}

See the HookToEvents example for a concrete use case.

Serial / Logging¶

By default, Homie for ESP8266 will output a lot of useful debug messages on the Serial. You may want to disable this behavior if you want to use the Serial line for anything else.

void setup() {
  Homie.enableLogging(false); // before Homie.setup()
  // ...
}

If logging is enabled Serial.begin(); will be called internally at 115 200 baud in Homie.setup(). So don't initialize the Serial line yourself.

Input handlers¶

There are three types of input handlers:

Global input handler. This unique handler will handle every changed subscribed properties for all registered nodes

bool globalInputHandler(String node, String property, String value) {

}

void setup() {
  Homie.setGlobalInputHandler(globalInputHandler); // before Homie.setup()
  // ...
}

* Node input handlers. This handler will handle every changed subscribed properties of a specific node

bool nodeInputHandler(String property, String value) {

}

HomieNode node("id", "type", nodeInputHandler);

* Property input handlers. This handler will handle changes for a specific property of a specific node

bool propertyInputHandler(String value) {

}

HomieNode node("id", "type");

void setup() {
  node.subscribe("property", propertyInputHandler); // before Homie.setup()
  // ...
}

You can see that input handlers return a boolean. An input handler can decide whether or not it handled the message and want to propagate it down to other input handlers. If an input handler returns true, the propagation is stopped, if it returns false, the propagation continues. The order of the propagation is global handler → node handler → property handler.

For example, imagine you defined three input handlers: the global one, the node one, and the property one. If the global input handler returns false, the node input handler will be called. If the node input handler returns true, the propagation is stopped and the property input handler won't be called.

HomieNode¶

You might want to create a node that subscribes to all properties. Just add a fourth parameter to the HomieNode constructor, set to true:

bool nodeInputHandler(String property, String value) {

}

HomieNode node("id", "type", nodeInputHandler, true);

See the LedStrip example for a concrete use case.

Reset¶

Resetting the device means erasing the stored configuration and rebooting from normal mode to configuration mode. By default, you can do it by pressing 5 seconds the FLASH button of your ESP8266 board.

This behavior is configurable:

void setup() {
  Homie.setResetTrigger(1, LOW, 2000); // before Homie.setup()
  // ...
}

The device will now reset if pin 1 is LOW for 2000ms. You can also disable completely this reset trigger:

void setup() {
  Homie.disableResetTrigger(); // before Homie.setup()
  // ...
}

In addition, you can also provide your own function responsible for the device reset. This function will be looped:

bool resetFunction () {
  return true; // If true is returned, the device will reset, if false, it won't
}

void setup() {
  Homie.setResetFunction(resetFunction); // before Homie.setup()
  // ...
}

Sometimes, you might want to disable temporarily the ability to reset the device. For example, if your device is doing some background work like moving shutters, you will want to disable the ability to reset until the shutters are not moving anymore.

Homie.setResettable(false);

Note that if a reset is asked while resettable is set to false, the device will be flagged. In other words, when you will call Homie.setResettable(true); back, the device will immediately reset.

Know if device is in normal mode¶

If, for some reason, you want to run some code in the Arduino loop() function, it might be useful for you to know if the device is in normal mode and if the network connection is up.

void loop() {
  if (Homie.isReadyToOperate()) {
    // normal mode and network connection up
  } else {
    // not in normal mode or network connection down
  }
}