Environmental Module

Last updated 12 days ago

This documentation includes hardware info, installation guidelines and sample code for your hardware.

Overall Info

Turta Environmental Module measures temperature, relative humidity, pressure, and gas resistance. Its driver calculates altitude if pressure at the sea level is given. User software can sense air quality. This module carries Bosch Sensortec BME680 environmental sensor.

Illustration

Top
Bottom

Module Connections

  • I2C: SCL and SDA.

  • POWER: +3.3V and GND.

Specifications

BME680's technical specifications are as follows:

  • Operating temperature range: -40 to 85 °C

  • Operating humidity range: 0 to 100% RH

  • Operating pressure range: 300 to 1100 hPa

  • Temperature accuracy: ± 0.5 °C at 25 °C

  • Humidity accuracy: ± 3% rH

  • Pressure noise: 0.12 Pa, equiv. to 1.7 cm

  • Factory calibrated.

Prerequisites

To get maximum performance from your hardware, please make sure you'll meet the following requirements.

Hardware

Environmental Module is an add-in board for Turta Modular System. You'll need a compatible host device for your module. The following devices support Environmental Module:

  • Turta IoT Node - ESP32

The temperature sensor is sensitive to surrounding temperatures. It is recommended to avoid overloading host device to keep it cool. So please ensure air flow to the sensor, e.g., open enough ventilation holes for the sensor and the host board. Besides, relative humidity is being calculated by using temperature reading. So, the temperature is also affecting relative humidity readings.

Software

For ESP32 based systems, we're currently supporting Arduino core. Please make sure you've installed the following:

  • Arduino IDE.

  • ESP32 Hardware libraries for the Arduino IDE.

  • Python for the compilation of Arduino projects.

  • Drivers for your host device, e.g., USB Virtual Serial Port driver.

Installation

You'll need to install a library to make Arduino IDE support the sensor. This library includes drivers for the BME680 sensor and sample code for you to jumpstart your project.

Libraries

Please download the library archive from https://github.com/Turta-io/Modular

Then, copy its contents to your Arduino Libraries folder.

You can find the Arduino Libraries folder inside your Arduino sketch directory. It is generally located inside the My Documents folder.

Samples

The library comes with included samples. There is no need to download additional files for the examples.

Source Code

The hardware, its drivers and the sample code are open source. You can use them under the terms of the MIT license. Please feel free to customize and prototype them for your projects.

Arduino Library

Turta_Environmental_Module library is responsible for initializing the sensor, reading calibration data and reading temperature, humidity, pressure, and gas resistance values with respect to calibration data. It also controls the heater in the sensor for gas resistance measurement.

To use the library on Arduino IDE, add the following #include statement to the top of your sketch.

#include <Turta_Environmental_Module.h>

Then, create an instance of the Turta_Environmental_Module class.

Turta_Environmental_Module en

Now you're ready to access the library by calling the en instance.

Initialization

To initialize the sensor, call the begin method.

begin()

This method turns the sensor on and then reads the calibration coefficients to the memory. It also sets the heater temperature to 250 °C and heating time to 250 ms for gas resistance reading.

Basic Members

Read Temperature

Returns the last temperature reading from the sensor.

double readTemperature()
  • Parameters

    • None

  • Returns

    • Double: Temperature

Read Humidity

Returns the relative humidity reading from the sensor.

double readHumidity()
  • Parameters

    • None

  • Returns

    • Double: Humidity

Read Pressure

Returns the pressure reading from the sensor.

double readPressure()
  • Parameters

    • None

  • Returns

    • Double: Pressure

Read Humidity

Returns the relative humidity reading from the sensor.

double readHumidity()
  • Parameters

    • None

  • Returns

    • Double: Humidity

Calculate Altitude

Returns the altitude from the sea level.

double calcAltitude(double meanSeaLevelPressureInBar)
  • Parameters

    • Double: meanSeaLevelPressureInBar

  • Returns

    • Double: Altitude

Read Gas Resistance

Returns the gas resistance reading from the sensor.

double readGasResistance()
  • Parameters

    • None

  • Returns

    • Double: Gas Resistance in Ohms

Read Temperature, Pressure, and Humidity in One Shot

Returns the temperature, pressure, and humidity reading from the sensor.

void readPressure(double temperature, double pressure, double humidity)
  • Parameters

    • Double: temperature out

    • Double: pressure out

    • Double: humidity out

  • Returns

    • None

Advanced Members

Advanced Initialization

To initialize the sensor with manual hot plate configuration, call the begin advanced method.

beginAdvanced(ushort heatDuration, uint heatTemperature)

This method turns the sensor on and then reads the calibration coefficients to the memory. It configures heater duration and temperature according to the given parameters.

  • Parameters

    • ushort: heatDuration

    • uint: heatTemperature

Examples

You can open the example from Arduino IDE > File > Examples > Examples from Custom Libraries > Turta Environmental Module. There are three examples of this sensor.

Single Readings

This application demonstrates temperature, humidity, pressure, altitude and gas resistance reading functions of the module. It uses Arduino IDE's Serial Monitor to display sensor readings.

To run the example:

  1. Open the IoT_Node_Environmental_Single_Readings sketch from the examples menu.

  2. Select Turta IoT Node from Tools > Board menu.

  3. Select your device's COM port from Tools > Port menu.

  4. Open Serial Monitor from Tools > Serial Monitor.

  5. Select 115.200 baud from the Serial Monitor's status bar.

  6. Upload the code to your device.

Sample Code

IoT_Node_Environmental_Single_Readings.ino
#include <Turta_Environmental_Module.h>
// Global Variables
double meanSeaLevelPressureInBar = 1020.0;
// Create Environmental Sensor instance.
Turta_Environmental_Module en;
void setup() {
// Initialize Environmental Sensor.
en.begin();
// Configure serial port.
Serial.begin(115200);
delay(200);
}
void loop() {
// Read temperature.
double temperature = en.readTemperature();
Serial.print("Temperature: ");
Serial.println(temperature);
// Read relative humidity.
double humidity = en.readHumidity();
Serial.print("Humidity: ");
Serial.println(humidity);
// Read pressure.
double pressure = en.readPressure();
Serial.print("Pressure: ");
Serial.println(pressure);
// Calculate altitude.
double altitude = en.calcAltitude(meanSeaLevelPressureInBar);
Serial.print("Altitude: ");
Serial.println(altitude);
// Read gas resistance.
double gasResistance = en.readGasResistance();
Serial.print("Gas Resistance: ");
Serial.println(gasResistance);
// Print an empty line.
Serial.println("");
// Delay 5000ms = 5 seconds.
delay(5000);
}

Result

After the application is uploaded to the device, it writes current readings to the Serial Monitor every five seconds. The example output should be like this:

Temperature: 25.26
Humidity: 57.37
Pressure: 1009.65
Altitude: 120.34
Gas Resistance: 121349.56

The application runs forever until you clear it from memory.

One Shot TPH

This application demonstrates temperature, pressure, and humidity reading functions of the module. It uses Arduino IDE's Serial Monitor to display sensor readings.

To run the example:

  1. Open the IoT_Node_Environmental_One_Shot_TPH sketch from the examples menu.

  2. Select Turta IoT Node from Tools > Board menu.

  3. Select your device's COM port from Tools > Port menu.

  4. Open Serial Monitor from Tools > Serial Monitor.

  5. Select 115.200 baud from the Serial Monitor's status bar.

  6. Upload the code to your device.

Sample Code

IoT_Node_Environmental_One_Shot_TPH.ino
#include <Turta_Environmental_Module.h>
// Create Environmental Sensor instance.
Turta_Environmental_Module en;
void setup() {
// Initialize Environmental Sensor.
en.begin();
// Configure serial port.
Serial.begin(115200);
delay(200);
}
void loop() {
// Read temperature, pressure, and humidity in one shot.
double temperature, pressure, humidity;
en.readTPH(temperature, pressure, humidity);
// Print temperature.
Serial.print("Temperature: ");
Serial.println(temperature);
// Print relative humidity.
Serial.print("Humidity: ");
Serial.println(humidity);
// Print pressure.
Serial.print("Pressure: ");
Serial.println(pressure);
// Print an empty line.
Serial.println("");
// Delay 5000ms = 5 seconds.
delay(5000);
}

Result

After the application is uploaded to the device, it writes current readings to the Serial Monitor every five seconds. The example output should be like this:

Temperature: 25.26
Humidity: 57.37
Pressure: 1009.65

The application runs forever until you clear it from memory.

Gas Settings

This application demonstrates manual configuration of the gas resistance reading functions of the module. It uses Arduino IDE's Serial Monitor to display sensor readings.

To run the example:

  1. Open the IoT_Node_Environmental_Gas_Settings sketch from the examples menu.

  2. Select Turta IoT Node from Tools > Board menu.

  3. Select your device's COM port from Tools > Port menu.

  4. Open Serial Monitor from Tools > Serial Monitor.

  5. Select 115.200 baud from the Serial Monitor's status bar.

  6. Upload the code to your device.

Sample Code

IoT_Node_Environmental_Gas_Settings.ino
#include <Turta_Environmental_Module.h>
// Create Environmental Sensor instance.
Turta_Environmental_Module en;
void setup() {
// Initialize Environmental Sensor.
// Heat Duration: 150secs, Heat Temperature: 300C
en.beginAdvanced(150, 300);
// Configure serial port.
Serial.begin(115200);
delay(200);
}
void loop() {
// Read gas resistance.
double gasResistance = en.readGasResistance();
Serial.print("Gas Resistance: ");
Serial.println(gasResistance);
// Delay 5000ms = 5 seconds.
delay(5000);
}

Result

After the application is uploaded to the device, it writes current readings to the Serial Monitor every five seconds. The example output should be like this:

Gas Resistance: 121349.56

The application runs forever until you clear it from memory.

Troubleshooting

If you're experiencing difficulties while working with your device, please try the following steps.

Problem: You're reading NaN instead of sensor data. Cause: The host device does not communicate with the sensor over the I2C protocol. There is a software bug on the ESP32 Arduino hardware library which prevents I2C communication. Solution: Please update the ESP32 hardware library.

Problem: Temperature reading is above, and humidity reading is below from it should be. Cause: ESP32's CPU can reach up to 240MHz, which heats itself and surroundings. Solution: For temperature and humidity reading applications, it would be better first to read the sensor data, then run the other tasks. If you're making just a temperature & humidity sensing device, you may wish to DeepSleep the host device while it is idle.

Problem: Humidity reading is much higher than it should be. Cause: In some cases, moisture does not escape from the sensor quickly. Solution: Please run the example application for a few hours and observe if the humidity level is decreasing. If not, you can bake the sensor module at 100 °C for 15 minutes to make moisture escape from the sensor's measuring hole.

Problem: Sensor readings are not accurate after inserting the sensor to the slot, while the application is running. Cause: The sensor library reads the calibration coefficients at the beginning of the application. If you insert the sensor module after the application is started, the library does not get the calibration coefficients and return inaccurate readings. Solution: Please press the reset button on the host board, or upload the application again while the sensor module is in the sensor slot.