Skip to content

Home

Jump to bottom
nomis2001sk edited this page Jan 25, 2024 · 7 revisions

Welcome to the STS1 sensor library WIKI.

This library is intended to be used with either the STS1 Raspi-Hat or the EDU module.

Topics

  1. Dependencies
  2. Simple VS Advanced
  3. the simple path
  4. the advanced path
  5. Description of classes and their functions

Dependencies

In order for this library to function appropriately few things need to be considered.

First of all the library itself (STS1_Sensors.py)needs to be downloaded and saved into the directory where you are writing your code.

Moreover, two external libraries are mandatory. smbus2 is needed for the I2C communication with the sensors, and the time library is used for the BME688. As the smbus2 library is usually not preinstalled, you have to do that. This can be easily done by entering the following command:

sudo apt install python3-smbus2

Simple VS Advanced

The first thing you need to do when using this library is to decide whether you would like to go the simple or the advanced more complex (and dangerous :) ) path. I would advise you to first go the simple path and then if you really want it, go the advanced path.

Now, you may wonder what the difference between "the simple path" and "the advanced path" is. When using the library in the simple way you only have to do very few things (3 commands) in order to get values from the sensors. However, if you decide you want to play with the advanced stuff you have to think about many more things when using this library. But, if you really want to fine-tune the sensor this would be the way to go. A more detailed explanation can be found further down in this document.

the simple path

As you have probably already read, few things need to be done to get sensor values. Therefore I am going to explain this with some example code.

First of all, we need to import some libraries. The smbus2 library is used to communicate over I2C, the STS1 class from the library STS1_Sensors is used to use the sensors (who would have thought :) ), and last but not least the time library is needed in order to time some things. You will see that in more detail later in this document. As the name "STS1_Sensors" is quite long I gave it an alias called STS1.

from smbus2 import SMBus
import STS1_Sensors as STS1
import time

After importing the libraries we can start using them. This example is the minimum amount of code you need to write to get sensor values.

with SMBus(1) as bus:
    sensors = STS1.Sensors(bus)
    sensors.disable_BMM150()
    sensors.setup()
    val = sensors.getData()

Let's break down the above code into smaller pieces.

with SMBus(1) as bus:

This line of code basically calls the function SMBus() with the parameter 1 and puts the result into the variable bus. Parameter 1 just defines which hardware I2C bus (0 or 1) should be used.

In order to be able to use the functions defined in the library and more specifically in the class Sensors we need to initialize a variable with this class.

sensors = STS1.Sensors(bus)

sensors is only a variable which is set to the result of STS1.Sensors(bus). This needs to be done in order to get access to the functions.

Now that we have access to the functions let's use them. There are three basic functions. There is disable_XXXXXX(), setup() and getData(). They are rather self-explanatory. However, the order in which these functions are called is crucial. If you want to disable certain sensors (e.g. hardware malfunction) you need to do that before the setup function. Moreover, the getData function needs to be called after the setup function.

sensors.disable_BMM150()
sensors.setup()
val = sensors.getData()

Now you know how and when to call the functions. The function getData spits out an object of the type SensorsData. In this case, this is saved into val. You can access the individual values as follows:

val.tempBME #temperature value of the BME sensor

A list and description of this class and all functions can be found at the end of this document.

Now you should know everything to have some fun with these sensors. Below there is an example which uses all of the things I described.

from smbus2 import SMBus
import STS1_Sensors as STS1
import time

with SMBus(1) as bus:
    sensors = STS1.Sensors(bus)
    sensors.disable_BMM150()
    sensors.setup()
    while True:      
        string = "TempBME: {0:.2f} °C | Hum: {1:.2f} % | Press: {2:.2f} hPa | GasRes:{3:.2f} Ohms | TempTMP: {4:.2f} | GX: {5:.2f} | GY: {6:.2f} | GZ: {7:.2f} | UVA: {8:.2f}"
        val = sensors.getData()
        print(string.format(val.tempBME, val.hum, val.press / 100.0, val.gasRes, val.tempTMP, val.gX, val.gY, val.gZ, val.uva))
        time.sleep(1)

the advanced path

So you have chosen the advanced path. The class Sensors which is used in "the simple way" is just a wrapper (fancy packaging) which manages the use of each individual sensor class (e.g. BME688, BMM150, ADXL345 . . .). Therefore if you want more control of the individual sensors you can also use these sensor classes directly. Below you can find a short example. As this is the advanced path there will be no further explanation. But I advise you to consult the individual datasheets of theses sensors and also the chapter "Description of classes and their functions". Have fun.

from smbus2 import SMBus
import STS1_Sensors as STS1
import time

with SMBus(1) as bus:
    ADXL = STS1.ADXL345(bus)
    ADXL.set_address(0x53)
    ADXL.set_datarate(100)
    ADXL.set_range(2)
    ADXL.setup()
    while True:
        string = "GX: {0:.2f} | GY: {1:.2f} | GZ: {2:.2f}"
        print(string.format(ADXL.getXGs(), ADXL.getYGs(), ADXL.getZGs()))
        time.sleep(0.1)

Description of classes and their functions

Before you scroll thru the eternity of function and class description, keep in mind that you can also look at the code of the library to better understand functions and classes.

twos_comp(val, bits)

This function calculates the two's complement representation of a given val using the specified number of bits.

Arguments

val (integer): The value to convert to two's complement representation.
bits (integer): The number of bits to use for the two's complement representation.

Returns

twos_comp (integer): The two's complement representation of val.

current_millis_time()

This function returns the current time in milliseconds

Arguments

This function takes no arguments.

Returns

current_millis_time (integer): The current time in milliseconds.

class SensorsData()

SensorsData is a class which is used to return the sensor values when using the Sensors class. The SensorsData class is a simple data container class that is used to store sensor readings. It defines a number of fields for storing different types of sensor readings, including temperature, humidity, pressure, and acceleration.

Fields

* tempTMP (float): The temperature reading from the TMP112 sensor, in degrees Celsius.
* tempBME (float): The temperature reading from the BME688 sensor, in degrees Celsius.
* hum (float): The humidity reading from the BME688 sensor, as a percentage.
* press (float): The pressure reading from the BME688 sensor, in Pascals.
* gasRes (float): The gas resistance reading from the BME688 sensor, in Ohms.
* accX (float): The acceleration reading in the X direction from the ADXL345 sensor, in m/s^2.
* accY (float): The acceleration reading in the Y direction from the ADXL345 sensor, in m/s^2.
* accZ (float): The acceleration reading in the Z direction from the ADXL345 sensor, in m/s^2.
* gX (float): The acceleration reading in the X direction from the ADXL345 sensor, in Gs.
* gY (float): The acceleration reading in the Y direction from the ADXL345 sensor, in Gs.
* gZ (float): The acceleration reading in the Z direction from the ADXL345 sensor, in Gs.
* uva (float): The UVA radiation reading from the GUVA-C32 sensor 0-65536.
* uvaI (float): The UVA index reading from the GUVA-C32 sensor 0-16.
* magX (float): The magnetic field reading in the X direction from the BMM150 sensor, in microteslas.
* magY (float): The magnetic field reading in the Y direction from the BMM150 sensor, in microteslas.
* magZ (float): The magnetic field reading in the Z direction from the BMM150 sensor, in microteslas.

class Sensors()

The Sensors class is a wrapper for all individual sensor classes to make the use of them simpler.

Functions * init(self, bus) initializes the class * disable_BME688(self) disables the BME688 * disable_TMP112(self) disables the TMP112 * disable_ADXL345(self) disables the ADXL345 * disable_BMM150(self) disables the BMM150 * disable_GUVA_C32(self) disables the GUVA_C32 * setup(self) sets up all individual enabled sensors accordingly with hardcoded default parameters * getData(self) reads out all enabled sensors and returns them as an object with type of SensorsData

class TMP112()

A class for the TMP112

Functions

* __init__(self, bus) initializes the class
* deact_consoleLog(self) deactivates debug messages in the console
* set_mode(self, mode) choose between extended mode (1) and normal mode (0)
* set_address(self, address) set I2C device address
* set_conversionrate(self, rate) sets conversionrate
* setup(self) initializes the sensor, all set functions must be called before this
* getTemp(self) reads the temp and returns it as a float in °C

class bmeData()

bmeData is a class which is used to return the sensor values when using the BME688 class. The bmeData class is a simple data container class that is used to store sensor readings. It defines a number of fields for storing different types of sensor readings, including temperature, humidity, pressure, and gas resistance.

Fields

* temperature (float): The temperature reading in °C.
* humidity (float): The humidity reading in %.
* pressure (float): The pressure reading in Pascals.
* gasResistance (float): The gas resistance reading in Ohms.
* AQI (float): The air quality index.

Functions

* __init__(self) initializes the class
* setTemp(self, temp) stores temp in temperature
* setHum(self, hum) stores hum in humidity
* setPress(self, press) stores press in pressure
* setGasRes(self, gasRes) stores gasRes in gasResistance
* setAQI(self, AQI) stores AQI in AQI

class BME688()

A class for the BME688

Functions

* __init__(self, bus) initializes the class
* deact_consoleLog(self) deactivates debug messages in the console
* set_address(self, address) set I2C device address
* set_tempOSR(self, OSR) sets the temperature oversampling rate
* set_humOSR(self, OSR) sets the humidity oversampling rate
* set_pressOSR(self, OSR) sets the pressure oversampling rate
* set_IIR(self, IIR) sets the IIR filter
* set_gasTemp(self, temp) sets the heater temperature for gas resistance measuring
* set_gasTime(self, time) sets the heater on time duration for gas resistance measuring
* setup(self) initializes the sensor, all set functions must be called before this
* getVal(self) reads all sensor values and returns them as an object of the type bmeData

class GUVA_C32()

A class for the GUVA_C32

Functions

* __init__(self, bus) initializes the class
* deact_consoleLog(self) deactivates debug messages in the console
* set_address(self, address) set I2C device address
* set_resolution(self, res) sets resolution
* set_range(self, range_) sets range
* setup(self) initializes the sensor, all set functions must be called before this
* getRawUVA(self) reads the sensor value and directly returns it 0-65536
* getUVA(self) reads the sensor value and returns it as an UV index from 0-16

class ADXL345()

A class for the ADXL345

Functions

* __init__(self, bus) initializes the class
* deact_consoleLog(self) deactivates debug messages in the console
* set_address(self, address) set I2C device address
* set_datarate(self, rate) sets the data rate
* set_range(self, range_) sets range
* setup(self) initializes the sensor, all set functions must be called before this
* getXRaw(self) reads the sensors X value and directly returns it
* getYRaw(self) reads the sensors Y value and directly returns it
* getZRaw(self) reads the sensors Z value and directly returns it
* getXGs(self) reads the sensors X value and returns it as a multiple of g
* getYGs(self) reads the sensors Y value and returns it as a multiple of g
* getZGs(self) reads the sensors Z value and returns it as a multiple of g

class BMM150()

A class for the BMM150

Functions

* __init__(self, bus) initializes the class
* deact_consoleLog(self) deactivates debug messages in the console
* set_address(self, address) set I2C device address
* set_datarate(self, rate) sets the data rate
* setup(self) initializes the sensor, all set functions must be called before this
* getXRaw(self) reads the sensors X value and directly returns it
* getYRaw(self) reads the sensors Y value and directly returns it
* getZRaw(self) reads the sensors Z value and directly returns it
* getXuT(self) reads the sensors X value and returns it as uT
* getYuT(self) reads the sensors Y value and returns it as uT
* getZuT(self) reads the sensors Z value and returns it as uT
Clone this wiki locally