BME68X Python example, docs and configure

2021-07-30 11:37:28 +01:00 · 2021-07-30 11:37:28 +01:00 · 618fd559f9
commit 618fd559f9
--- a/micropython/examples/breakout_bme68x/README.md
+++ b/micropython/examples/breakout_bme68x/README.md
@ -0,0 +1,91 @@
+# BME68X <!-- omit in toc -->
+
+- [Getting Started](#getting-started)
+- [Reading Data From The Sensor](#reading-data-from-the-sensor)
+- [Configuring The Sensor](#configuring-the-sensor)
+  - [Filter Settings](#filter-settings)
+  - [Oversampling Settings](#oversampling-settings)
+  - [Mode Settings](#mode-settings)
+  - [Standby/Output Data Rate Settings](#standbyoutput-data-rate-settings)
+  - [Defaults](#defaults)
+
+## Getting Started
+
+Construct new `PimoroniI2C` and `BreakoutBME68X` instances:
+
+```python
+from breakout_bme68x import BreakoutBME68X
+from pimoroni_i2c import PimoroniI2C
+
+PINS_BREAKOUT_GARDEN = {"sda": 4, "scl": 5}
+PINS_PICO_EXPLORER = {"sda": 20, "scl": 21}
+
+i2c = PimoroniI2C(**PINS_PICO_EXPLORER)
+bme = BreakoutBME68X(i2c)
+```
+
+The `breakout_bme68x` module includes constants for the possible I2C addresses:
+
+* `ADDRESS_DEFAULT`
+* `ADDRESS_ALT`
+
+## Reading Data From The Sensor
+
+The `read` method will return a tuple containing Temperature (degrees C), Pressure (Pa) humidity, and gas resistance values, plus the status code and gas/measurement indexes:
+
+```python
+temperature, pressure, humidity, gas_resistance, status, gas_index, meas_index = bme.read()
+```
+
+## Configuring The Sensor
+
+The `configure` method allows you to set up the oversampling, filtering and operation mode.
+
+```python
+bme.configure(filter, standby_time, os_pressure, os_temp, os_humidity)
+```
+
+The `breakout_bme68x` module includes constants for these:
+
+### Filter Settings
+
+* `FILTER_COEFF_OFF`
+* `FILTER_COEFF_1`
+* `FILTER_COEFF_3`
+* `FILTER_COEFF_8`
+* `FILTER_COEFF_15`
+* `FILTER_COEFF_31`
+* `FILTER_COEFF_63`
+* `FILTER_COEFF_127`
+
+### Oversampling Settings
+
+* `NO_OVERSAMPLING`
+* `OVERSAMPLING_1X`
+* `OVERSAMPLING_2X`
+* `OVERSAMPLING_4X`
+* `OVERSAMPLING_8X`
+* `OVERSAMPLING_16X`
+
+### Mode Settings
+
+* `SLEEP_MODE`
+* `FORCED_MODE`
+* `NORMAL_MODE`
+
+### Standby/Output Data Rate Settings
+
+* `STANDBY_TIME_0_59_MS`
+* `STANDBY_TIME_62_5_MS`
+* `STANDBY_TIME_125_MS`
+* `STANDBY_TIME_250_MS`
+* `STANDBY_TIME_500_MS`
+* `STANDBY_TIME_1000_MS`
+* `STANDBY_TIME_10_MS`
+* `STANDBY_TIME_20_MS`
+
+### Defaults
+
+```python
+bme.configure(FILTER_COEFF_3, STANDBY_TIME_1000_MS, OVERSAMPLING_16X, OVERSAMPLING_2X, OVERSAMPLING_1X)
+```
--- a/micropython/examples/breakout_bme68x/bme68x_demo.py
+++ b/micropython/examples/breakout_bme68x/bme68x_demo.py
@ -0,0 +1,18 @@
+"""BME688 / BME680 demo
+
+This demo will work for both the BME680 and BME688.
+"""
+import time
+from breakout_bme68x import BreakoutBME68X
+from pimoroni_i2c import PimoroniI2C
+
+PINS_BREAKOUT_GARDEN = {"sda": 4, "scl": 5}
+PINS_PICO_EXPLORER = {"sda": 20, "scl": 21}
+
+i2c = PimoroniI2C(**PINS_PICO_EXPLORER)
+bmp = BreakoutBME68X(i2c, address=0x77)
+
+while True:
+    reading = bmp.read()
+    print(reading)
+    time.sleep(1.0)
--- a/micropython/modules/breakout_bme68x/breakout_bme68x.c
+++ b/micropython/modules/breakout_bme68x/breakout_bme68x.c
@ -6,6 +6,7 @@

 /***** Methods *****/
 MP_DEFINE_CONST_FUN_OBJ_1(BreakoutBME68X_read_obj, BreakoutBME68X_read);
+MP_DEFINE_CONST_FUN_OBJ_KW(BreakoutBME68X_configure_obj, 1, BreakoutBME68X_configure);

 /***** Binding of Methods *****/
 STATIC const mp_rom_map_elem_t BreakoutBME68X_locals_dict_table[] = {
@ -31,6 +32,42 @@ const mp_obj_type_t breakout_bme68x_BreakoutBME68X_type = {
 STATIC const mp_map_elem_t breakout_bme68x_globals_table[] = {
    { MP_OBJ_NEW_QSTR(MP_QSTR___name__), MP_OBJ_NEW_QSTR(MP_QSTR_breakout_bme68x) },
    { MP_OBJ_NEW_QSTR(MP_QSTR_BreakoutBME68X), (mp_obj_t)&breakout_bme68x_BreakoutBME68X_type },
+
+    { MP_ROM_QSTR(MP_QSTR_FILTER_COEFF_OFF), MP_ROM_INT(BME68X_FILTER_OFF) },
+    { MP_ROM_QSTR(MP_QSTR_FILTER_COEFF_1), MP_ROM_INT(BME68X_FILTER_SIZE_1) },
+    { MP_ROM_QSTR(MP_QSTR_FILTER_COEFF_3), MP_ROM_INT(BME68X_FILTER_SIZE_3) },
+    { MP_ROM_QSTR(MP_QSTR_FILTER_COEFF_7), MP_ROM_INT(BME68X_FILTER_SIZE_7) },
+    { MP_ROM_QSTR(MP_QSTR_FILTER_COEFF_15), MP_ROM_INT(BME68X_FILTER_SIZE_15) },
+    { MP_ROM_QSTR(MP_QSTR_FILTER_COEFF_31), MP_ROM_INT(BME68X_FILTER_SIZE_31) },
+    { MP_ROM_QSTR(MP_QSTR_FILTER_COEFF_63), MP_ROM_INT(BME68X_FILTER_SIZE_63) },
+    { MP_ROM_QSTR(MP_QSTR_FILTER_COEFF_127), MP_ROM_INT(BME68X_FILTER_SIZE_127) },
+
+    { MP_ROM_QSTR(MP_QSTR_NO_OVERSAMPLING), MP_ROM_INT(BME68X_OS_NONE) },
+    { MP_ROM_QSTR(MP_QSTR_OVERSAMPLING_1X), MP_ROM_INT(BME68X_OS_1X) },
+    { MP_ROM_QSTR(MP_QSTR_OVERSAMPLING_2X), MP_ROM_INT(BME68X_OS_2X) },
+    { MP_ROM_QSTR(MP_QSTR_OVERSAMPLING_4X), MP_ROM_INT(BME68X_OS_4X) },
+    { MP_ROM_QSTR(MP_QSTR_OVERSAMPLING_8X), MP_ROM_INT(BME68X_OS_8X) },
+    { MP_ROM_QSTR(MP_QSTR_OVERSAMPLING_16X), MP_ROM_INT(BME68X_OS_16X) },
+
+/*  TODO add MicroPython support for alternate reading modes?
+    { MP_ROM_QSTR(MP_QSTR_SLEEP_MODE), MP_ROM_INT(BME68X_SLEEP_MODE) },
+    { MP_ROM_QSTR(MP_QSTR_FORCED_MODE), MP_ROM_INT(BME68X_FORCED_MODE) },
+    { MP_ROM_QSTR(MP_QSTR_PARALLEL_MODE), MP_ROM_INT(BME68X_PARALLEL_MODE) },
+    { MP_ROM_QSTR(MP_QSTR_SEQUENTIAL_MODE), MP_ROM_INT(BME68X_SEQUENTIAL_MODE) },
+*/
+
+    { MP_ROM_QSTR(MP_QSTR_STANDBY_TIME_OFF), MP_ROM_INT(BME68X_ODR_NONE) },
+    { MP_ROM_QSTR(MP_QSTR_STANDBY_TIME_0_59_MS), MP_ROM_INT(BME68X_ODR_0_59_MS) },
+    { MP_ROM_QSTR(MP_QSTR_STANDBY_TIME_62_5_MS), MP_ROM_INT(BME68X_ODR_62_5_MS) },
+    { MP_ROM_QSTR(MP_QSTR_STANDBY_TIME_125_MS), MP_ROM_INT(BME68X_ODR_125_MS) },
+    { MP_ROM_QSTR(MP_QSTR_STANDBY_TIME_250_MS), MP_ROM_INT(BME68X_ODR_250_MS) },
+    { MP_ROM_QSTR(MP_QSTR_STANDBY_TIME_500_MS), MP_ROM_INT(BME68X_ODR_500_MS) },
+    { MP_ROM_QSTR(MP_QSTR_STANDBY_TIME_1000_MS), MP_ROM_INT(BME68X_ODR_1000_MS) },
+    { MP_ROM_QSTR(MP_QSTR_STANDBY_TIME_10_MS), MP_ROM_INT(BME68X_ODR_10_MS) },
+    { MP_ROM_QSTR(MP_QSTR_STANDBY_TIME_20_MS), MP_ROM_INT(BME68X_ODR_20_MS) },
+
+    { MP_ROM_QSTR(MP_QSTR_I2C_ADDRESS_DEFAULT), MP_ROM_INT(BME68X_I2C_ADDR_LOW) },
+    { MP_ROM_QSTR(MP_QSTR_I2C_ADDRESS_ALT), MP_ROM_INT(BME68X_I2C_ADDR_HIGH) },
 };
 STATIC MP_DEFINE_CONST_DICT(mp_module_breakout_bme68x_globals, breakout_bme68x_globals_table);

--- a/micropython/modules/breakout_bme68x/breakout_bme68x.cpp
+++ b/micropython/modules/breakout_bme68x/breakout_bme68x.cpp
@ -102,4 +102,30 @@ mp_obj_t BreakoutBME68X_read(mp_obj_t self_in) {
    }
 }

+mp_obj_t BreakoutBME68X_configure(size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) {
+    enum { ARG_self, ARG_filter, ARG_standby_time, ARG_os_pressure, ARG_os_temp, ARG_os_humidity };
+    static const mp_arg_t allowed_args[] = {
+        { MP_QSTR_, MP_ARG_REQUIRED | MP_ARG_OBJ },
+        { MP_QSTR_filter, MP_ARG_INT, { .u_int=BME68X_FILTER_SIZE_3 } },
+        { MP_QSTR_standby_time, MP_ARG_INT, { .u_int=BME68X_ODR_0_59_MS } },
+        { MP_QSTR_os_pressure, MP_ARG_INT, { .u_int=BME68X_OS_16X } },
+        { MP_QSTR_os_temp, MP_ARG_INT, { .u_int=BME68X_OS_2X } },
+        { MP_QSTR_os_humidity, MP_ARG_INT, { .u_int=BME68X_OS_1X } }
+    };
+
+    mp_arg_val_t args[MP_ARRAY_SIZE(allowed_args)];
+    mp_arg_parse_all(n_args, pos_args, kw_args, MP_ARRAY_SIZE(allowed_args), allowed_args, args);
+
+    breakout_bme68x_BreakoutBME68X_obj_t *self = MP_OBJ_TO_PTR2(args[ARG_self].u_obj, breakout_bme68x_BreakoutBME68X_obj_t);
+    self->breakout->configure(
+        args[ARG_filter].u_int,
+        args[ARG_standby_time].u_int,
+        args[ARG_os_humidity].u_int,
+        args[ARG_os_pressure].u_int,
+        args[ARG_os_temp].u_int
+    );
+
+    return mp_const_none;
+}
+
 }
--- a/micropython/modules/breakout_bme68x/breakout_bme68x.h
+++ b/micropython/modules/breakout_bme68x/breakout_bme68x.h
@ -1,5 +1,6 @@
 // Include MicroPython API.
 #include "py/runtime.h"
+#include "drivers/bme68x/src/bme68x_defs.h"

 /***** Constants *****/

@ -9,4 +10,5 @@ extern const mp_obj_type_t breakout_bme68x_BreakoutBME68X_type;
 /***** Extern of Class Methods *****/
 extern void BreakoutBME68X_print(const mp_print_t *print, mp_obj_t self_in, mp_print_kind_t kind);
 extern mp_obj_t BreakoutBME68X_make_new(const mp_obj_type_t *type, size_t n_args, size_t n_kw, const mp_obj_t *all_args);
-extern mp_obj_t BreakoutBME68X_read(mp_obj_t self_in);
+extern mp_obj_t BreakoutBME68X_read(mp_obj_t self_in);
+extern mp_obj_t BreakoutBME68X_configure(size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args);