ESPHome 2026.3.0-dev
Loading...
Searching...
No Matches
esphome::bme680::BME680Component Class Reference

#include <bme680.h>

Inheritance diagram for esphome::bme680::BME680Component:
esphome::PollingComponent esphome::i2c::I2CDevice esphome::Component

Public Member Functions

void set_temperature_oversampling (BME680Oversampling temperature_oversampling)
 Set the temperature oversampling value. Defaults to 16X.
 
void set_pressure_oversampling (BME680Oversampling pressure_oversampling)
 Set the pressure oversampling value. Defaults to 16X.
 
void set_humidity_oversampling (BME680Oversampling humidity_oversampling)
 Set the humidity oversampling value. Defaults to 16X.
 
void set_iir_filter (BME680IIRFilter iir_filter)
 Set the IIR Filter value. Defaults to no IIR Filter.
 
void set_temperature_sensor (sensor::Sensor *temperature_sensor)
 
void set_pressure_sensor (sensor::Sensor *pressure_sensor)
 
void set_humidity_sensor (sensor::Sensor *humidity_sensor)
 
void set_gas_resistance_sensor (sensor::Sensor *gas_resistance_sensor)
 
void set_heater (uint16_t heater_temperature, uint16_t heater_duration)
 Set how the internal heater should operate.
 
void setup () override
 
void dump_config () override
 
void update () override
 
- Public Member Functions inherited from esphome::PollingComponent
 PollingComponent ()
 
 PollingComponent (uint32_t update_interval)
 Initialize this polling component with the given update interval in ms.
 
virtual void set_update_interval (uint32_t update_interval)
 Manually set the update interval in ms for this polling object.
 
void call_setup () override
 
virtual uint32_t get_update_interval () const
 Get the update interval in ms of this sensor.
 
void start_poller ()
 
void stop_poller ()
 
- Public Member Functions inherited from esphome::Component
virtual void loop ()
 This method will be called repeatedly.
 
virtual float get_setup_priority () const
 priority of setup().
 
float get_actual_setup_priority () const
 
void set_setup_priority (float priority)
 
virtual float get_loop_priority () const
 priority of loop().
 
void call ()
 
virtual void on_shutdown ()
 
virtual void on_safe_shutdown ()
 
virtual bool teardown ()
 Called during teardown to allow component to gracefully finish operations.
 
virtual void on_powerdown ()
 Called after teardown is complete to power down hardware.
 
uint8_t get_component_state () const
 
void reset_to_construction_state ()
 Reset this component back to the construction state to allow setup to run again.
 
bool is_in_loop_state () const
 Check if this component has completed setup and is in the loop state.
 
bool is_idle () const
 Check if this component is idle.
 
void mark_failed ()
 Mark this component as failed.
 
 ESPDEPRECATED ("Use mark_failed(LOG_STR(\"static string literal\")) instead. Do NOT use .c_str() from temporary " "strings. Will stop working in 2026.6.0", "2025.12.0") void mark_failed(const char *message)
 
void mark_failed (const LogString *message)
 
void disable_loop ()
 Disable this component's loop.
 
void enable_loop ()
 Enable this component's loop.
 
void enable_loop_soon_any_context ()
 Thread and ISR-safe version of enable_loop() that can be called from any context.
 
bool is_failed () const
 
bool is_ready () const
 
virtual bool can_proceed ()
 
bool status_has_warning () const
 
bool status_has_error () const
 
void status_set_warning (const char *message=nullptr)
 
void status_set_warning (const LogString *message)
 
void status_set_error ()
 
 ESPDEPRECATED ("Use status_set_error(LOG_STR(\"static string literal\")) instead. Do NOT use .c_str() from temporary " "strings. Will stop working in 2026.6.0", "2025.12.0") void status_set_error(const char *message)
 
void status_set_error (const LogString *message)
 
void status_clear_warning ()
 
void status_clear_error ()
 
void status_momentary_warning (const char *name, uint32_t length=5000)
 Set warning status flag and automatically clear it after a timeout.
 
void status_momentary_error (const char *name, uint32_t length=5000)
 Set error status flag and automatically clear it after a timeout.
 
bool has_overridden_loop () const
 
void set_component_source (const LogString *source)
 Set where this component was loaded from for some debug messages.
 
const LogString * get_component_log_str () const
 Get the integration where this component was declared as a LogString for logging.
 
bool should_warn_of_blocking (uint32_t blocking_time)
 
- Public Member Functions inherited from esphome::i2c::I2CDevice
 I2CDevice ()=default
 we use the C++ default constructor
 
void set_i2c_address (uint8_t address)
 We store the address of the device on the bus.
 
uint8_t get_i2c_address () const
 Returns the I2C address of the object.
 
void set_i2c_bus (I2CBus *bus)
 we store the pointer to the I2CBus to use
 
I2CRegister reg (uint8_t a_register)
 calls the I2CRegister constructor
 
I2CRegister16 reg16 (uint16_t a_register)
 calls the I2CRegister16 constructor
 
ErrorCode read (uint8_t *data, size_t len) const
 reads an array of bytes from the device using an I2CBus
 
ErrorCode read_register (uint8_t a_register, uint8_t *data, size_t len)
 reads an array of bytes from a specific register in the I²C device
 
ErrorCode read_register16 (uint16_t a_register, uint8_t *data, size_t len)
 reads an array of bytes from a specific register in the I²C device
 
ErrorCode write (const uint8_t *data, size_t len) const
 writes an array of bytes to a device using an I2CBus
 
ErrorCode write_read (const uint8_t *write_data, size_t write_len, uint8_t *read_data, size_t read_len) const
 writes an array of bytes to a device, then reads an array, as a single transaction
 
ErrorCode write_register (uint8_t a_register, const uint8_t *data, size_t len) const
 writes an array of bytes to a specific register in the I²C device
 
ErrorCode write_register16 (uint16_t a_register, const uint8_t *data, size_t len) const
 write an array of bytes to a specific register in the I²C device
 
bool read_bytes (uint8_t a_register, uint8_t *data, uint8_t len)
 Compat APIs All methods below have been added for compatibility reasons.
 
bool read_bytes_raw (uint8_t *data, uint8_t len) const
 
template<size_t N>
optional< std::array< uint8_t, N > > read_bytes (uint8_t a_register)
 
template<size_t N>
optional< std::array< uint8_t, N > > read_bytes_raw ()
 
bool read_bytes_16 (uint8_t a_register, uint16_t *data, uint8_t len)
 
bool read_byte (uint8_t a_register, uint8_t *data)
 
optional< uint8_t > read_byte (uint8_t a_register)
 
bool read_byte_16 (uint8_t a_register, uint16_t *data)
 
bool write_bytes (uint8_t a_register, const uint8_t *data, uint8_t len) const
 
bool write_bytes (uint8_t a_register, const std::vector< uint8_t > &data) const
 
template<size_t N>
bool write_bytes (uint8_t a_register, const std::array< uint8_t, N > &data)
 
bool write_bytes_16 (uint8_t a_register, const uint16_t *data, uint8_t len) const
 
bool write_byte (uint8_t a_register, uint8_t data) const
 
bool write_byte_16 (uint8_t a_register, uint16_t data) const
 

Protected Member Functions

uint8_t calc_heater_resistance_ (uint16_t temperature)
 Calculate the heater resistance value to send to the BME680 register.
 
uint8_t calc_heater_duration_ (uint16_t duration)
 Calculate the heater duration value to send to the BME680 register.
 
void read_data_ ()
 Read data from the BME680 and publish results.
 
float calc_temperature_ (uint32_t raw_temperature)
 Calculate the temperature in °C using the provided raw ADC value.
 
float calc_pressure_ (uint32_t raw_pressure)
 Calculate the pressure in hPa using the provided raw ADC value.
 
float calc_humidity_ (uint16_t raw_humidity)
 Calculate the relative humidity in % using the provided raw ADC value.
 
float calc_gas_resistance_ (uint16_t raw_gas, uint8_t range)
 Calculate the gas resistance in Ω using the provided raw ADC value.
 
uint32_t calc_meas_duration_ ()
 Calculate how long the sensor will take until we can retrieve data.
 
- Protected Member Functions inherited from esphome::Component
void call_loop_ ()
 
void call_dump_config_ ()
 
void set_component_state_ (uint8_t state)
 Helper to set component state (clears state bits and sets new state)
 
bool set_status_flag_ (uint8_t flag)
 Helper to set a status LED flag on both this component and the app.
 
void set_interval (uint32_t id, uint32_t interval, std::function< void()> &&f)
 Set an interval function with a numeric ID (zero heap allocation).
 
void set_interval (InternalSchedulerID id, uint32_t interval, std::function< void()> &&f)
 
void set_interval (uint32_t interval, std::function< void()> &&f)
 
bool cancel_interval (uint32_t id)
 
bool cancel_interval (InternalSchedulerID id)
 
ESPDEPRECATED("set_retry is deprecated and will be removed in 2026.8.0. Use set_timeout or set_interval instead.", "2026.2.0") void set_retry(const std ESPDEPRECATED ("set_retry is deprecated and will be removed in 2026.8.0. Use set_timeout or set_interval instead.", "2026.2.0") void set_retry(const char *name
 
 ESPDEPRECATED ("set_retry is deprecated and will be removed in 2026.8.0. Use set_timeout or set_interval instead.", "2026.2.0") void set_retry(uint32_t id
 
 ESPDEPRECATED ("set_retry is deprecated and will be removed in 2026.8.0. Use set_timeout or set_interval instead.", "2026.2.0") void set_retry(uint32_t initial_wait_time
 
ESPDEPRECATED("cancel_retry is deprecated and will be removed in 2026.8.0.", "2026.2.0") bool cancel_retry(const std ESPDEPRECATED ("cancel_retry is deprecated and will be removed in 2026.8.0.", "2026.2.0") bool cancel_retry(const char *name)
 
 ESPDEPRECATED ("cancel_retry is deprecated and will be removed in 2026.8.0.", "2026.2.0") bool cancel_retry(uint32_t id)
 
void set_timeout (uint32_t id, uint32_t timeout, std::function< void()> &&f)
 Set a timeout function with a numeric ID (zero heap allocation).
 
void set_timeout (InternalSchedulerID id, uint32_t timeout, std::function< void()> &&f)
 
void set_timeout (uint32_t timeout, std::function< void()> &&f)
 
bool cancel_timeout (uint32_t id)
 
bool cancel_timeout (InternalSchedulerID id)
 
void defer (std::function< void()> &&f)
 Defer a callback to the next loop() call.
 
void defer (uint32_t id, std::function< void()> &&f)
 Defer a callback with a numeric ID (zero heap allocation)
 
bool cancel_defer (uint32_t id)
 

Protected Attributes

BME680CalibrationData calibration_
 
BME680Oversampling temperature_oversampling_ {BME680_OVERSAMPLING_16X}
 
BME680Oversampling pressure_oversampling_ {BME680_OVERSAMPLING_16X}
 
BME680Oversampling humidity_oversampling_ {BME680_OVERSAMPLING_16X}
 
BME680IIRFilter iir_filter_ {BME680_IIR_FILTER_OFF}
 
uint16_t heater_temperature_ {320}
 
uint16_t heater_duration_ {150}
 
sensor::Sensortemperature_sensor_ {nullptr}
 
sensor::Sensorpressure_sensor_ {nullptr}
 
sensor::Sensorhumidity_sensor_ {nullptr}
 
sensor::Sensorgas_resistance_sensor_ {nullptr}
 
- Protected Attributes inherited from esphome::PollingComponent
uint32_t update_interval_
 
- Protected Attributes inherited from esphome::Component
ESPDEPRECATED("Use const char* or uint32_t overload instead. Removed in 2026.7.0", "2026.1.0") void set_interval(const std voi set_interval )(const char *name, uint32_t interval, std::function< void()> &&f)
 Set an interval function with a unique name.
 
ESPDEPRECATED("Use const char* or uint32_t overload instead. Removed in 2026.7.0", "2026.1.0") bool cancel_interval(const std boo cancel_interval )(const char *name)
 Cancel an interval function.
 
ESPDEPRECATED("set_retry is deprecated and will be removed in 2026.8.0. Use set_timeout or set_interval instead.", "2026.2.0") void set_retry(const std uint32_t initial_wait_time
 
ESPDEPRECATED("set_retry is deprecated and will be removed in 2026.8.0. Use set_timeout or set_interval instead.", "2026.2.0") void set_retry(const std uint32_t uint8_t max_attempts
 
ESPDEPRECATED("set_retry is deprecated and will be removed in 2026.8.0. Use set_timeout or set_interval instead.", "2026.2.0") void set_retry(const std uint32_t uint8_t std::function< RetryResult(uint8_t)> && f
 
ESPDEPRECATED("set_retry is deprecated and will be removed in 2026.8.0. Use set_timeout or set_interval instead.", "2026.2.0") void set_retry(const std uint32_t uint8_t std::function< RetryResult(uint8_t)> float backoff_increase_factor = 1.0f)
 
uint32_t initial_wait_time
 
uint32_t uint8_t max_attempts
 
uint32_t uint8_t std::function< RetryResult(uint8_t)> && f
 
uint32_t uint8_t std::function< RetryResult(uint8_t)> float backoff_increase_factor = 1.0f)
 
uint8_t max_attempts
 
uint8_t std::function< RetryResult(uint8_t)> && f
 
uint8_t std::function< RetryResult(uint8_t)> float backoff_increase_factor = 1.0f)
 
ESPDEPRECATED("Use const char* or uint32_t overload instead. Removed in 2026.7.0", "2026.1.0") void set_timeout(const std voi set_timeout )(const char *name, uint32_t timeout, std::function< void()> &&f)
 Set a timeout function with a unique name.
 
ESPDEPRECATED("Use const char* or uint32_t overload instead. Removed in 2026.7.0", "2026.1.0") bool cancel_timeout(const std boo cancel_timeout )(const char *name)
 Cancel a timeout function.
 
ESPDEPRECATED("Use const char* overload instead. Removed in 2026.7.0", "2026.1.0") void defer(const std voi defer )(const char *name, std::function< void()> &&f)
 Defer a callback to the next loop() call.
 
ESPDEPRECATED("Use const char* overload instead. Removed in 2026.7.0", "2026.1.0") bool cancel_defer(const std boo cancel_defer )(const char *name)
 Cancel a defer callback using the specified name, name must not be empty.
 
const LogString * component_source_ {nullptr}
 
uint16_t warn_if_blocking_over_ {WARN_IF_BLOCKING_OVER_MS}
 Warn if blocked for this many ms (max 65.5s)
 
uint8_t component_state_ {0x00}
 State of this component - each bit has a purpose: Bits 0-2: Component state (0x00=CONSTRUCTION, 0x01=SETUP, 0x02=LOOP, 0x03=FAILED, 0x04=LOOP_DONE) Bit 3: STATUS_LED_WARNING Bit 4: STATUS_LED_ERROR Bit 5: Has overridden loop() (set at registration time) Bits 6-7: Unused - reserved for future expansion.
 
volatile bool pending_enable_loop_ {false}
 ISR-safe flag for enable_loop_soon_any_context.
 
- Protected Attributes inherited from esphome::i2c::I2CDevice
uint8_t address_ {0x00}
 store the address of the device on the bus
 
I2CBusbus_ {nullptr}
 pointer to I2CBus instance
 

Detailed Description

Definition at line 69 of file bme680.h.

Member Function Documentation

◆ calc_gas_resistance_()

float esphome::bme680::BME680Component::calc_gas_resistance_ ( uint16_t raw_gas,
uint8_t range )
protected

Calculate the gas resistance in Ω using the provided raw ADC value.

Definition at line 456 of file bme680.cpp.

◆ calc_heater_duration_()

uint8_t esphome::bme680::BME680Component::calc_heater_duration_ ( uint16_t duration)
protected

Calculate the heater duration value to send to the BME680 register.

Definition at line 280 of file bme680.cpp.

◆ calc_heater_resistance_()

uint8_t esphome::bme680::BME680Component::calc_heater_resistance_ ( uint16_t temperature)
protected

Calculate the heater resistance value to send to the BME680 register.

Definition at line 249 of file bme680.cpp.

◆ calc_humidity_()

float esphome::bme680::BME680Component::calc_humidity_ ( uint16_t raw_humidity)
protected

Calculate the relative humidity in % using the provided raw ADC value.

Definition at line 420 of file bme680.cpp.

◆ calc_meas_duration_()

uint32_t esphome::bme680::BME680Component::calc_meas_duration_ ( )
protected

Calculate how long the sensor will take until we can retrieve data.

Definition at line 473 of file bme680.cpp.

◆ calc_pressure_()

float esphome::bme680::BME680Component::calc_pressure_ ( uint32_t raw_pressure)
protected

Calculate the pressure in hPa using the provided raw ADC value.

Definition at line 378 of file bme680.cpp.

◆ calc_temperature_()

float esphome::bme680::BME680Component::calc_temperature_ ( uint32_t raw_temperature)
protected

Calculate the temperature in °C using the provided raw ADC value.

Definition at line 352 of file bme680.cpp.

◆ dump_config()

void esphome::bme680::BME680Component::dump_config ( )
overridevirtual

Reimplemented from esphome::Component.

Definition at line 213 of file bme680.cpp.

◆ read_data_()

void esphome::bme680::BME680Component::read_data_ ( )
protected

Read data from the BME680 and publish results.

Definition at line 296 of file bme680.cpp.

◆ set_gas_resistance_sensor()

void esphome::bme680::BME680Component::set_gas_resistance_sensor ( sensor::Sensor * gas_resistance_sensor)
inline

Definition at line 83 of file bme680.h.

◆ set_heater()

void esphome::bme680::BME680Component::set_heater ( uint16_t heater_temperature,
uint16_t heater_duration )

Set how the internal heater should operate.

By default, the heater is off. If you want to to have more reliable humidity and Gas Resistance values, you can however setup the heater with this method.

Parameters
heater_temperatureThe temperature of the heater in °C.
heater_durationThe duration in ms that the heater should turn on for when measuring.

Definition at line 506 of file bme680.cpp.

◆ set_humidity_oversampling()

void esphome::bme680::BME680Component::set_humidity_oversampling ( BME680Oversampling humidity_oversampling)

Set the humidity oversampling value. Defaults to 16X.

Definition at line 502 of file bme680.cpp.

◆ set_humidity_sensor()

void esphome::bme680::BME680Component::set_humidity_sensor ( sensor::Sensor * humidity_sensor)
inline

Definition at line 82 of file bme680.h.

◆ set_iir_filter()

void esphome::bme680::BME680Component::set_iir_filter ( BME680IIRFilter iir_filter)

Set the IIR Filter value. Defaults to no IIR Filter.

Definition at line 505 of file bme680.cpp.

◆ set_pressure_oversampling()

void esphome::bme680::BME680Component::set_pressure_oversampling ( BME680Oversampling pressure_oversampling)

Set the pressure oversampling value. Defaults to 16X.

Definition at line 499 of file bme680.cpp.

◆ set_pressure_sensor()

void esphome::bme680::BME680Component::set_pressure_sensor ( sensor::Sensor * pressure_sensor)
inline

Definition at line 81 of file bme680.h.

◆ set_temperature_oversampling()

void esphome::bme680::BME680Component::set_temperature_oversampling ( BME680Oversampling temperature_oversampling)

Set the temperature oversampling value. Defaults to 16X.

Definition at line 496 of file bme680.cpp.

◆ set_temperature_sensor()

void esphome::bme680::BME680Component::set_temperature_sensor ( sensor::Sensor * temperature_sensor)
inline

Definition at line 80 of file bme680.h.

◆ setup()

void esphome::bme680::BME680Component::setup ( )
overridevirtual

Reimplemented from esphome::Component.

Definition at line 73 of file bme680.cpp.

◆ update()

void esphome::bme680::BME680Component::update ( )
overridevirtual

Implements esphome::PollingComponent.

Definition at line 236 of file bme680.cpp.

Field Documentation

◆ calibration_

BME680CalibrationData esphome::bme680::BME680Component::calibration_
protected

Definition at line 123 of file bme680.h.

◆ gas_resistance_sensor_

sensor::Sensor* esphome::bme680::BME680Component::gas_resistance_sensor_ {nullptr}
protected

Definition at line 134 of file bme680.h.

◆ heater_duration_

uint16_t esphome::bme680::BME680Component::heater_duration_ {150}
protected

Definition at line 129 of file bme680.h.

◆ heater_temperature_

uint16_t esphome::bme680::BME680Component::heater_temperature_ {320}
protected

Definition at line 128 of file bme680.h.

◆ humidity_oversampling_

BME680Oversampling esphome::bme680::BME680Component::humidity_oversampling_ {BME680_OVERSAMPLING_16X}
protected

Definition at line 126 of file bme680.h.

◆ humidity_sensor_

sensor::Sensor* esphome::bme680::BME680Component::humidity_sensor_ {nullptr}
protected

Definition at line 133 of file bme680.h.

◆ iir_filter_

BME680IIRFilter esphome::bme680::BME680Component::iir_filter_ {BME680_IIR_FILTER_OFF}
protected

Definition at line 127 of file bme680.h.

◆ pressure_oversampling_

BME680Oversampling esphome::bme680::BME680Component::pressure_oversampling_ {BME680_OVERSAMPLING_16X}
protected

Definition at line 125 of file bme680.h.

◆ pressure_sensor_

sensor::Sensor* esphome::bme680::BME680Component::pressure_sensor_ {nullptr}
protected

Definition at line 132 of file bme680.h.

◆ temperature_oversampling_

BME680Oversampling esphome::bme680::BME680Component::temperature_oversampling_ {BME680_OVERSAMPLING_16X}
protected

Definition at line 124 of file bme680.h.

◆ temperature_sensor_

sensor::Sensor* esphome::bme680::BME680Component::temperature_sensor_ {nullptr}
protected

Definition at line 131 of file bme680.h.


The documentation for this class was generated from the following files: