Binary Sensor

In esphomelib, every component that exposes a binary state, is a BinarySensor.

To create your own binary sensor, simply subclass BinarySensor and call BinarySensor::publish_state() to tell the frontend that you have a new state. Inversion is automatically done for you when publishing state and can be changed by the user with BinarySensor::set_inverted().

Example Usage

// Basic
App.register_binary_sensor(custom_binary_sensor);
// GPIO Binary Sensor
App.make_gpio_binary_sensor("Window Open", 36);

See Application::register_binary_sensor() and Application::make_gpio_binary_sensor().

API Reference

BinarySensor

class BinarySensor : public Nameable

Base class for all binary_sensor-type classes.

This class includes a callback that components such as MQTT can subscribe to for state changes. The sub classes should notify the front-end of new states via the publish_state() method which handles inverted inputs for you.

Subclassed by binary_sensor::ESP32TouchBinarySensor, binary_sensor::GPIOBinarySensorComponent, binary_sensor::PN532BinarySensor, binary_sensor::RDM6300BinarySensor, binary_sensor::StatusBinarySensor, binary_sensor::TemplateBinarySensor, display::NextionTouchComponent, ESP32BLEPresenceDevice, remote::RemoteReceiver

Public Functions

BinarySensor(const std::string &name)

Construct a binary sensor with the specified name.

Parameters
  • name: Name of this binary sensor.

void add_on_state_callback(std::function<void(bool)> &&callback)

Add a callback to be notified of state changes.

Parameters
  • callback: The void(bool) callback.

void publish_state(bool state)

Publish a new state to the front-end.

Parameters
  • state: The new state.

void set_device_class(const std::string &device_class)

Manually set the Home Assistant device class (see esphomelib::binary_sensor::device_class)

std::string get_device_class()

Get the device class for this binary sensor, using the manual override if specified.

PressTrigger *make_press_trigger()
ReleaseTrigger *make_release_trigger()
ClickTrigger *make_click_trigger(uint32_t min_length, uint32_t max_length)
DoubleClickTrigger *make_double_click_trigger(uint32_t min_length, uint32_t max_length)
MultiClickTrigger *make_multi_click_trigger(const std::vector<MultiClickTriggerEvent> &timing)
void add_filter(Filter *filter)
void add_filters(std::vector<Filter *> filters)
void send_state_internal_(bool state)
bool has_state() const

Return whether this binary sensor has outputted a state.

Public Members

bool state

The current reported state of the binary sensor.

union binary_sensor::BinarySensor::[anonymous] [anonymous]

Protected Functions

std::string device_class()

Get the default device class for this sensor, or empty string for no default.

Protected Attributes

CallbackManager<void(bool)> state_callback_ = {}
optional<std::string> device_class_ = {}

Stores the override of the device class.

Filter *filter_list_ = {nullptr}
bool has_state_ = {false}

MQTTBinarySensorComponent

class MQTTBinarySensorComponent : public mqtt::MQTTComponent

Simple MQTT front-end component for a binary_sensor.

After construction of this class, it should be connected to the BinarySensor by setting the callback returned by create_on_new_state_callback() in BinarySensor::on_new_state().

Public Functions

MQTTBinarySensorComponent(BinarySensor *binary_sensor)

Construct a MQTTBinarySensorComponent.

Parameters
  • binary_sensor: The binary sensor.

void setup()

Send discovery.

void dump_config()
void send_discovery(JsonObject &obj, mqtt::SendDiscoveryConfig &config)

Send Home Assistant discovery info.

void set_is_status(bool status)
void send_initial_state()
void publish_state(bool state)
bool is_internal()

Protected Functions

std::string friendly_name() const

Return the friendly name of this binary sensor.

std::string component_type() const

“binary_sensor” component type.

Protected Attributes

BinarySensor *binary_sensor_
bool is_status_ = {false}

Filters

class Filter

Subclassed by binary_sensor::DelayedOffFilter, binary_sensor::DelayedOnFilter, binary_sensor::HeartbeatFilter, binary_sensor::InvertFilter, binary_sensor::LambdaFilter, binary_sensor::UniqueFilter

Public Functions

virtual optional<bool> new_value(bool value) = 0
void input(bool value)
void output(bool value)

Protected Attributes

friend binary_sensor::Filter::BinarySensor
Filter *next_ = {nullptr}
BinarySensor *parent_ = {nullptr}
class DelayedOnFilter : public binary_sensor::Filter, public Component

Public Functions

DelayedOnFilter(uint32_t delay)
optional<bool> new_value(bool value)
float get_setup_priority() const

priority of setup().

higher -> executed earlier

Defaults to 0.

Return
The setup priority of this component

Protected Attributes

uint32_t delay_
class DelayedOffFilter : public binary_sensor::Filter, public Component

Public Functions

DelayedOffFilter(uint32_t delay)
optional<bool> new_value(bool value)
float get_setup_priority() const

priority of setup().

higher -> executed earlier

Defaults to 0.

Return
The setup priority of this component

Protected Attributes

uint32_t delay_
class HeartbeatFilter : public binary_sensor::Filter, public Component

Public Functions

HeartbeatFilter(uint32_t interval)
optional<bool> new_value(bool value)
void setup()

Where the component’s initialization should happen.

Analogous to Arduino’s setup(). This method is guaranteed to only be called once. Defaults to doing nothing.

float get_setup_priority() const

priority of setup().

higher -> executed earlier

Defaults to 0.

Return
The setup priority of this component

Protected Attributes

uint32_t interval_
optional<bool> value_ = {}
class InvertFilter : public binary_sensor::Filter

Public Functions

optional<bool> new_value(bool value)
class LambdaFilter : public binary_sensor::Filter

Public Functions

LambdaFilter(const std::function<optional<bool>(bool)> &f)
optional<bool> new_value(bool value)

Protected Attributes

std::function<optional<bool>bool)> binary_sensor::LambdaFilter::f_
class UniqueFilter : public binary_sensor::Filter

Public Functions

optional<bool> new_value(bool value)

Protected Attributes

optional<bool> last_value_ = {}

Triggers

class PressTrigger : public Trigger<NoArg>

Public Functions

PressTrigger(BinarySensor *parent)
class ReleaseTrigger : public Trigger<NoArg>

Public Functions

ReleaseTrigger(BinarySensor *parent)
class ClickTrigger : public Trigger<NoArg>

Public Functions

ClickTrigger(BinarySensor *parent, uint32_t min_length, uint32_t max_length)

Protected Attributes

uint32_t start_time_ = {0}
uint32_t min_length_

The millis() time when the click started.

uint32_t max_length_

Minimum length of click. 0 means no minimum.

class DoubleClickTrigger : public Trigger<NoArg>

Public Functions

DoubleClickTrigger(BinarySensor *parent, uint32_t min_length, uint32_t max_length)

Protected Attributes

uint32_t start_time_ = {0}
uint32_t end_time_ = {0}
uint32_t min_length_
uint32_t max_length_

Minimum length of click. 0 means no minimum.

class MultiClickTrigger : public Trigger<NoArg>, public Component

Public Functions

MultiClickTrigger(BinarySensor *parent, const std::vector<MultiClickTriggerEvent> &timing)
void setup()

Where the component’s initialization should happen.

Analogous to Arduino’s setup(). This method is guaranteed to only be called once. Defaults to doing nothing.

float get_setup_priority() const

priority of setup().

higher -> executed earlier

Defaults to 0.

Return
The setup priority of this component

void set_invalid_cooldown(uint32_t invalid_cooldown)

Protected Functions

void on_state_(bool state)
void schedule_cooldown_()
void schedule_is_valid_(uint32_t min_length)
void schedule_is_not_valid_(uint32_t max_length)
void trigger_()

Protected Attributes

BinarySensor *parent_
std::vector<MultiClickTriggerEvent> timing_
uint32_t invalid_cooldown_ = {1000}
optional<size_t> at_index_ = {}
bool last_state_ = {false}
bool is_in_cooldown_ = {false}
bool is_valid_ = {false}