BME280 Module
=============

This module provides an easy-to-use interface for communicating with the BME280 chip, a popular environmental sensor that measures temperature, humidity, and pressure.

.. note:: The Lua module is included in the Xedge32 firmware but may be removed in later versions and provided as a separate module.


The Bosch Sensortec BME280/BMP280 temperature/air pressure/humidity sensor communicates with the ESP32 using the :ref:`I2C interface <I2C API>`. See the `BME280 Lua Source Code <https://github.com/RealTimeLogic/Xedge-ESP32/blob/master/Lua-Examples/.lua/bme280.lua>`_ for details.

Usage
-----

To use this module, you first need to create a BME280 object by calling the ``create`` function and passing the following parameters:

module.create()
---------------

.. code-block:: lua

   bme=require"bme280".create(port, address, sda, scl, settings)

Create a BME280 object.

**Parameters:**

- ``port`` (``int``): I2C port number, e.g., ``0``
- ``address`` (``int``): the BME280 I2C address, typically ``0x76``
- ``sda`` (``int``): the GPIO number used for the I2C Serial Data
- ``scl`` (``int``): the GPIO number used for the I2C Serial Clock
- ``settings`` (``table``, optional): a Lua table with settings. See the `WeatherStation demo <https://github.com/RealTimeLogic/LSP-Examples/tree/master/Sparkplug#ready-to-run-sparkplug-enabled-weather-station-example>`_ for example code.

**Returns:**

- A new BME280 object.

BME280 Object Methods
---------------------

bme:read()
~~~~~~~~~~~

.. code-block:: lua

   local temperature, humidity, pressure = bme:read()


Reads the temperature, humidity, and pressure from the BME280 sensor.

**Returns:**

- Three values: the temperature (in degrees Celsius), the humidity (as a percentage), and the pressure (in Pascals).

BME280 Examples
----------------

Basic example
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Here's an example of how to use the ``bme280`` module:

.. code-block:: lua

    local bmeModule = require"bme280"
    local port = 0
    local address = 0x76
    local sda = 5
    local scl = 6
    local bme = bmeModule.create(port, address, sda, scl)
    local temp, hum, pres = bme:read()

This example creates a new BME280 object, reads the temperature, humidity, and pressure from the sensor, and stores the values in the ``temp``, ``hum``, and ``pres`` variables. Note that we've assumed that the I2C port, address, SDA, and SCL pins are specified as local variables. You may need to adjust these variables to fit your specific use case.

Online Examples
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

- `bme280.xlua <https://github.com/RealTimeLogic/LSP-Examples/blob/master/ESP32/bme280.xlua>`_
- `Weather Station <https://github.com/surfskidude/weather-station>`_