tvocEn - digital-codes/critical-workshops GitHub Wiki

Die deutsche Version ist hier

The sensor setup requires 4 components plus cables. We aim to provide a small platform to mount the sensors onto. If this fails, our arrangement will be a bit messy like the one below. However, it should work alike.

ESP32 based development kit Atom Matrix

Inside, the Atom looks like this:

We can see a small integrated circuit (IC or chips), resistors, capactors, the USB connector and some other components mounted on a small printed cicruit boaord (PCB). The actual microcontroller is another IC located on the opposite side of the PCB, invisible but similar.

TVOC/eCO2 Gas Sensor Unit SGP30

Temperature and barometric pressure BMP280

To connect all of the above we need the hub

We need 3 cables to connect sensors and controller to the hub. The have different length but essentially the same function.

We also need a USB cable to hook up the Atom to your computer

We need to write a program to tell the microcontroller (the atom, remember?) how to read the sensor values and how to show the results to us.

In order to accomplish this, we need a couple of tools as shown below:

From left to right, counterclockwise:

• The atom and the sensors
• Your computer, attached to the atom with a USB cable
  • Your computer needs to run a program called M5Burn, which does some basic things with the atom via the USB cable.
  • Your computer needs to open a webpage on the M5Stack server called M5Flow which allows you to write the program for the atom. M5Flow also connects to your atom - not via USB but via the internet directly. This is the reason why your atom needs to connect to the internet as well. So, you must provide it with your wireless credentials. This is done with M5Burn. Sounds complicated? We're here to help.
• M5Stack server provides you with a list of all the capabilities of your sensor system and how you can use them. It also takes care of translating Your Program into a format suitable for the microcontroller: computers read numbers while humans read letters and words - or pictures.

In case you've never written a program before: don't be afraid! On our easy track it'll be easier than you might think.

If you are already familiar with Arduino or similar things: Yes, there is also a fast lane: In the UIFlow IDE there is the possibility to toggle thePython code. Take a look at this with the sample code from Introduction. You can then program directly in Python after completing the Downloads section.

The download page of M5Stack provides a couple of programs for all major platforms (Windows, MacOS and Linux):

We need M5Burner, please download and install the version for your operating system. You might also need the CP2104 driver (probably you don't if on Linux). This is all you need if you follow the easy track. We have more detailed instructions for Linux: Install M5 Stack on Linux.

The UIFlow-Desktop-IDE is the equivalent to the M5Stack server, so you can run the development environment directly on your computer. Please note: we couldn't test this approach yet. So if you get stuck we might not be able to help immediately.

Arduino-IDE is a completely different kind of tool. While the atom is not an Arduino with respect to physical layout it is software compatible to a large extent. The M5Stack Library gives your Arduino-IDE access to all the features of the atom and the sensors. No blockly neither python though - but we didn't talk about that anyway yet.

Further information and instructions can be found at M5Stack

• Quick Start

• UIFlow Programming Basics plus following chapters

• RGB

• PDF with extensive description

• Firmware Update Video

• IDE Video

Attention: This information is partly for a different controller than the Atom Matrix.

All controllers sent by the ZKM are already equipped with the start program. However, it can happen that something goes wrong during programming and we then have to restore this initial configuration with M5Burner.

To start, we unpack all the components and connect the controller, sensors and the I2C hub using the cables supplied. These 4-colored cables are of different lengths, but otherwise the same. So you don't have to be careful which cable was in which box.

The black USB cable is connected to the computer and then plugged into the controller next to the I2C cable. After that, all LEDs should be on Controller light up red.

There is a notched switch on the side of the controller. When pressed, the controller will restart. This is the reset button.

The entire area with the LEDs is also a push button. You feel and hear the click when you press it.

Click-Video

The controller can start in 3 operating modes

• Network Mode - for connecting to UIFlow on the Internet
• USB Mode - to connect to UIFlow via USB
• Application mode - Starts the last programmed application

See also Quickstart (above).

If we switch on the controller normally - i.e. plug in the USB cable, they start in application mode. Without special programming of the LEDs, all LEDs are switched to red, see above.

If you press the LED button (and keep it pressed) and briefly press the reset button, the controller switches to one Selection mode, which is indicated by changing the color green - blue - yellow / purple.

Select-Video

The point in time at which you release the LED button determines the further operating mode. To work with UIFlow in USB mode you have to we let go at blue. The LED field then also remains blue. If not, it was too fast or too slow - please try again.

When the LEDs light up blue, you can start the UIFlow IDE. Select the correct "COM" interface and the controller on the left second row, that's the atom matrix.

But what is the "COM" interface? Depending on the computer and operating system, the USB connection to the controller is either found immediately or not. Then an additional program has to be installed, the CP2104 driver, as indicated above. When this is done, should be in the selection field for "COM" something to be found. You may have to test various settings, click on "Refresh" and see whether "Connected" is displayed (both at the bottom left in the UIFlow window).

Please restart the UIFlow IDE after you have installed the driver for the COM interface and connected the controller via USB. It may also be necessary to restart your computer.

When "Connected" is displayed, you are ready to load the first program onto the controller. An example program can be found in the repository at this point (right click to download). It is possible (especially with a MAC) that the example gets a different file extension when it is downloaded and is therefore no longer recognized by UIFlow. Then either rename it again to example1.m5f or [download] the whole repository as a ZIP file (https://github.com/digital-codes/critical-workshops/archive/main.zip) and then unzip. The file is then in the subdirectory tvoc.

Load the program onto the computer and open it with UIFlow via the menu at the top right:Open

The program is then loaded onto the controller, also via the menu at the top right with Download. After that it should be on the controller executed as seen here

If that works, there are a few more basic examples you can use before developing your own programs:

Attention: If you write the configuration to the controller with M5Burner, a WLAN configuration is also generated. If you do not enter anything or the correct configuration here, the controller may try for a very long time after starting, to establish a connection with invalid data. There is no LED display - the display on the controller remains black. The method described above for selecting the USB mode should still work, at the latest after you have connected the USB cable pulled and stuck again.

System configuration

When creating a new program in UIFlow, in addition to the correct controller Atom Matrix, the two sensors must also be configured. This is done in the left panel by adding the appropriate Units, with the large **+**sign.

Mark the units BPS and TVOC in the selection.

Then the two sensors are visible in the Features in the middle panel under Units.

For each of the two sensors, different functions are then made available for selection when clicked. For the BPS sensor, for example, these are getTemperature and getPressure.

The TVOC sensor offers comparable functions. The control for the LEDs can be found at Hardwares/RGB.

The other features used in the examples below are below in the categories

• Logic
• Math
• Loops
• Timer
• Variables

With a little trial and error, you will surely find your way around.

Please note that all functions that you add to the program must form a coherent block, which is inserted below the yellow SETUP symbol (at least that applies to the simple examples here at the beginning).

Reading out the temperature sensor

The sensor should not be read out just once, but permanently. To do this, you need a while loop from the Loops. Insert the simple True symbol from the Logic category as a condition. Read out the sensor within the loop and display different color patterns on the LED matrix depending on the temperature. The following areas are provided in the example:

• <20 °
• <22 °
• <25 °
• <27 °
• Otherwise

Use the comparison operator = from the Logic set for the query. Change the operator to less than <, before that insert a query from the sensor get "bps0" temperature and then the temperature value from the Math set.

The queries cannot be written with several simple IF s one below the other, but they have to be nested:

Since the graphical Blockly programming is translated into Python, this can also be written with the simpler else-if syntax. You can generate the else-if using the top if (with the gear symbol) in the Logic set. With the number wheel, further else-if and the final else branch can be set under the first if.

In this case, the Wait 1s block at the end is only used to save power, since query and display do not have to be carried out at the highest speed.

Optimization can still be achieved by using a variable. The variable is defined in the Variables set with any name, e.g. temperature and can then also be called up here. Then the sensor is read out at the beginning of the loop and the value is saved in the variable. The variable is then used in the comparison operations, but no more sensor interrogations are carried out. This method reduces the number of times the sensor is accessed within one loop pass. Access to variables is faster and more energy efficient.

Now load the program tvoc-loop from the code repository onto your controller. After the start, the blue or green display will usually be active. If you heat the BPS sensor, e.g. with your hand or breathing air, the temperature display should change. Please note that the sensor is heated, not the controller.

Reading out the TVOC sensor

The TVOC sensor offers not only 2, but 8 values. At the moment only the eCO2 value is of interest. The other values ​​can be derived from the data sheet of the sensor from the manufacturer Sensirion. Unfortunately, the description of M5Stack does not contain all information.

It is used in the same way as the temperature sensor. TheeCO2value calculated by the sensor corresponds approximately to the CO2 content in the room air and is specified in ppm (parts per million). The indoor climate can be deduced from the CO2 share. The CO2 content is usually around 400ppm. Less than 300ppm indicate a defect in the sensor or incorrect programming. The "green area" is between 400 and 800-1000ppm. Beyond that, how quickly it gets "bad" is somewhat difficult to define. We refer, for example, to the report by the Federal Environment Agency. Quote:

In Finland the maximum permissible CO2 concentration in the indoor air under normal weather conditions is 1200 ppm. The Norwegian and Swedish guidelines provide for a maximum CO2 concentration of 1000 ppm for living rooms, schools and offices.

As a rule of thumb you may use the following categories:

• Up to 1000ppm: harmless
• 1000 - 2000ppm: ventilation necessary
• Above 2000ppm: leave room

The TVOC sensor reacts very sensitively to blowing, the values sometimes go well over 5000ppm.

Summary

You are now able to read the basic valuesCO2andtemperaturefrom the two sensors, assign the values to certain areas and implement a suitable display on the LED matrix.

You need the access data of your WLAN and a token from the workshop

The Atom Matrix controller not only has an LED display, but can also be via your WLAN Establish an Internet connection via which you can send the sensor data to a server.

We have set up a public Dashboard for this purpose. If you received a token and a number in the workshop, you will see your sensor data there under this number.

The program reads the two values ​​in a loop and transfers them to the OK Lab server with an HTTP POST request.

All you have to do is enter your WLAN access data and the token. If there are any errors, you can use the color coding find out where the problem is. If everything goes well, the display should pedal between blue-green (start of transmission) and green (transmission completed). The waiting time is preset to 15 minutes. You should not permanently decrease this value.

The code tvoc-net can be found in the code repository.

You can also transfer the remaining sensor data to the dashboard. Please use the following keys

• pres (air pressure from the BPS)
• h2 (h2 and remaining values ​​from TVOC)
• eth
• tvoc
• baseiaq
• baseco2
• basetvoc

You can create a new key using the + at the bottom of the create map block.

Attention: If the WLAN access data is not correct, the connection setup will be repeated very often. During this time there is no LED display. If you do not see any display after programming, the WLAN is probably not configured correctly.

You can register your sensor on Opensensemap to publish the data in a similar fashion as above.

Please look at our example sensor OK-Box-01

More infos to follow, stay tuned ....

Start with the registration and the example from the repository

For this example, create a new "custom" device on OpensenseMap with a sensor type "temperature". Opensense will then provide identifiers for the box "BOXID" and for the sensor "SENSORID", as well as an "access token". In the example code you have to replace the placeholders with the corresponding values. Furthermore you need access to your WLAN, so that the Atom can transfer data to OpensenseMap (like in the previous example). Enter the values for SSID and WIFI-PASSWORD.

Now the Atom will transmit the temperature regularly, which you can observe at the OpensenseMap website.

Add another sensor in your box for the CO2 value. OpensenseMap requires a separate transmission for each sensor, i.e. a new POST block with a different value for "SENSORID" is used each time.