# Tutorial on how to use temperature and humidity sensor(DHT11) with tig-stack

Project by: Baiwei Quan(bq222aj)

This simple project aims to provide clear instructions on how to realize a typical ioT system with the help of tig-stack all the way from collecting and formatting data to eventually visualizing the data.

Approximated time: 1 hour.

## Objective
As a computer science student, software development has always been the focus for me. For some reason, tinkering with hardware has evaded me all these years. However, I have always had hardware in mind. As a result, I took the ioT course as my first foray into the realm of hardware.

Since this is the first project involving hardware, I decided to start out simple by making the most basic project within ioT topics as a proof of concept. Despite the simplicity of this project, I believe it would still give you a good idea of how everything in a typical ioT system cohere with each other and some detailed inner workings in the tig-stack.

## Material
Since this project is rather simple, all the material required, except for the DHT11 temperature and humidity sensor and my own windows computer, can be bought in a [bundle](https://www.electrokit.com/produkt/lnu-1dt305-tillampad-iot-lopy4-basic-bundle/) at the price of approximately 97.80 US dollars. The following is included in the bundle.
| Name | Usage | Link |
| -------- | -------- | -------- |
| 1x Pycom LoPy4 with headers | collecting data from sensors, processing the data collected using Micro Python onboard and forward the processed data to a network server | [Learn more](https://pycom.io/product/lopy4/) |
| 1x Pycom Universal Expansion Board | facilitating and providing easy access to the pins on the pycom micro controller | [Learn more](https://pycom.io/product/expansion-board-3-0/) |
| 1x Micro USB cable | providing power suppy to lopy4 and the expansion board, and delivering the data to the computer | |

**Notes and Recommendations:**
* the antenna included in the [**bundle**](https://www.electrokit.com/produkt/lnu-1dt305-tillampad-iot-lopy4-basic-bundle/) is not used in this project and it is recommended to use the included usb cable since certain micro usb cable cannot transmit data.
* DHT11 temperature and humidity sensor was actually borrowed from a friend. Apparently, there exists a much better and more sensative alternative, i.e. DHT22 sensor. If quality of the measurement is important, DHT22 is highly recommended. (Note: the change of a sensor could lead to a changed library in micro python)
## Computer setup
### Integrated Development Environment

An IDE is required to work with the pycom device. It is basically a developer friendly text editor with useful functionalities such as built-in terminals and plugin support. In an IDE, one's code can be written, debugged, executed and transmitted. Two popular alternatives can be chosen between VS Code and Atom.

I chose VS Code, partly because I have had it installed on my computer since the software development days and partly because the latest Atom release just didn't work with the Pymakr plugin which I will talk about in a second.

A complete setup of VS Code from how to install the software to how to download plugins can be found [**here**](https://www.youtube.com/watch?v=MlIzFUI1QGA).

### Pymakr

Micro Python is the programming language that is chosen to be used in this project since there is already a MicroPython interpreter that can execute the code onboard the pycom device. In other words, the source code does not have to be compiled on the computer to be run but rather to be directly transferred to the micro controller.

Pymakr plugin is a mandatory component that can be downloaded directly in VS Code in order to enable the communication between the computer and the pycom device. Without this plugin, Python code cannot be transferred to the pycom device to be executed.

However, it won't work without Node.js software which can also be downloaded onto your computer for free. The installation of Node.js is straightforward. If you are unsure how to do that, click [**here**](https://www.youtube.com/watch?v=AuCuHvgOeBY). **Note**: ADD TO PATH option must be selected for it to work with VS Code.

### Upload the code

Upon completion of all the softwares above, restart the computer and start VS Code. This Pymakr plugin Tab should show up at the bottom. 
Simply press **Upload** to upload your MicroPython code to your pycom device once you are satisfied with it.

## Putting everything together


Note: **-(Minus)** sign on the sensor is connected to the GND(Ground) pin on the pycom device while **S(Signal)** sign is connected to P23(a general purpose pin to receive digital information from the DHT11 sensor). That leaves us the pin in the middle which connects to 3V3 pin on the device.

Note: You don't have to connect to P23 as I did. Since we only read input data from the sensor, it is recommended to use the pins from P23 to P13. Other pins could be occupied by other functions such as WIFI, it is not recommended to use them.

## Platform

There are quite many platforms to choose from based on your preferred connectivity. Pycom LoPy4 even has a built-in library to natively support Cloud based platform [**Pybytes**](https://pybytes.pycom.io/) to manage and visualize your data. It is very easy to use but it does lack in some other aspects compared to some of the other software or platforms.

Pycom LoPy4 supports multiple bands and connectivities such as Wifi, Bluetooth, LoRawan and Sigfox. Although LoRawan has increased substantially in its coverage globally, I could barely see more than 2 gateways in my proximity. Unfortunately, Sigfox is out of the picture for me too. That is why I settled with Wifi and hosting my own local platform with the help of Mosquitto and tig-stack both of which I will talk about in a minute.

### Mosquitto

Mosquitto is a free software that enables a mqtt broker locally. It can run on a windows powered computer which I use in my project or a smaller device such as a raspberry pi. Follow this [video tutorial](https://www.youtube.com/watch?v=72u6gIkeqUc) and ignore the security part to set up your mosquitto broker.
***IMPORTANT***: To make the latest Mosquitto work, listener port has to be added and allow_anonymous has to be set to true in the mosquitto.conf file which can be edited using Notepad++ run in administrator mode in the mosquitto directory. See the images below for reference.


Another important thing to do for Mosquitto to function is to create a new rule for the windows firewalls. In my project, only inbound rule is required since the data collected from the sensor will only be accessed locally.
To do that:
1. click windows logo and then type firewall, you will see Windows Defender Firewall comes up. Click on that, you will be brought to the Windows defender firewall app.
2. Now that you are in the app, you can see Advanced settings to the left. Click on that.
3. Now another window will pop up. on the left panel you will see Inbound Rules. Click on that.
4. On the Actions panel to the very right, you can see a New Rule option. Click on that.
5. Yet another window pop up. Because we are using port 1883 as the the MQTT port, we need to select the Port option and then select Next.
6. Select All programs and then press Next.
7. Select Allow the connection and press Next.
8. Select your preferences here and press Next. I for instance select all three options.
9. Give the rule a name, e.g. mosquitto. and finish the rule.
10. Now you are good to go with mosquitto.

**Extra:**
MQTT Explorer is a nifty application that can visualize the interactivity between the MQTT clients and the broker but it is not mandatory in this project.

### TIG-Stack

TIG Stack stand for Telegraf, InfluxDB, and Grafana. In this project a docker compose file will be used with TIG-Stack because of its simplicity of getting all three components up and running in a matter of seconds.

However, the initial setup could be intimidating. Therefore it is recommended to watch [this setup tutorial](https://www.youtube.com/watch?v=kimH1ENvalg) before proceeding further.

Notes: if you have watched the video, you should have a folder named tig-stack on your computer which contains at least a docker-compose.yml and a telegraf.conf. So far you might still have questions about how to setup your own broker locally since the video only shows you how to connect to a remote MQTT server. In order to do that, we will only edit the telegra.conf file as follows:

[agent]
  flush_interval = "15s"
  interval = "15s"


[[inputs.mqtt_consumer]]
  name_override = "MyServer"
  # Note: find out your computer's local ip address by typing ipconfig in a cmd terminal
  servers = ["mqtt://your_computer_local_ip_address:1883"]
  qos = 2
  connection_timeout = "30s"
  topics = [ "home/temperature/get"]
  data_format = "json"

[[outputs.influxdb]]
  database = "iot"
  urls = [ "http://influxdb:8086" ]
  username = "iotlnu"
  password = "micropython"

## The code
The file structure for this project should look like the image below in VS Code.
In the lib folder, [dht.py](https://github.com/JurassicPork/DHT_PyCom/blob/master/dth.py) and [mqtt.py](https://github.com/pycom/pycom-libraries/blob/master/examples/mqtt/mqtt.py) should be found as shown below.

The Code below is for the pycom device to connect to your local wifi router. I have a separate config file in the same folder which contains all my credentials which is why you see config.WIFI_SSID. If you don't care security, just fill in your WIFI SSID as a string instead of config.WIFI_SSID. The same goes for all the other config parameters.

# code in boot.py
from network import WLAN
import machine
import config

wlan = WLAN(mode=WLAN.STA)
wlan.connect(config.WIFI_SSID, auth=(WLAN.WPA2, config.WIFI_PASSWORD), timeout=5000)


while not wlan.isconnected():
    machine.idle()
print("Connected to WiFi\n")

The code below is to set up the MQTT client(the pycom device) and publish the sensor data to the broker hosted in mosquitto on your computer.

In connect_and_subscribe() function, you will set up MQTT client credentials and try to connect to the broker. You can name the MQTT client id whatever you want, MQTT server is your local ip address, port is 1883 as default.

In the while loop below, we try to read and publish data from the sensor every 5 seconds. Upon success of the reading, the data will be printed in the terminal and then formatted into a string in json and last but not least forwarded to the broker in accordance with the topics thansk to the publish() function.

# the code in main.py
from mqtt import MQTTClient
import time
import machine
from machine import Pin
from dht import DHT # https://github.com/JurassicPork/DHT_PyCom
import config

def connect_and_subscribe():
    client =  MQTTClient(config.MQTT_CLIENT_ID, config.MQTT_SERVER,port=config.MQTT_PORT)
    client.connect()
    print('Connected to MQTT broker')
    return client

def restart_and_reconnect():
    print('Failed to connect to MQTT broker. Reconnecting...')
    time.sleep(10)
    machine.reset()

try:
    client = connect_and_subscribe()
except OSError as e:
    restart_and_reconnect()

th = DHT(Pin('P23', mode=Pin.OPEN_DRAIN), 0)
time.sleep(2)

while True:
    result = th.read()
    while not result.is_valid():
        time.sleep(.5)
        result = th.read()
    print('Temp:', result.temperature)
    print('RH:', result.humidity)
    message = "{ \"temp\": %f, \"humidity\": %f}" % (result.temperature, result.humidity)
    print(message)
    client.publish(topic=config.MQTT_PUB_TOPIC, msg=message)
    time.sleep(5)

## Transmitting the data / connectivity
As you can see below, the data flow is quite straight-forward when it comes to transmission protocol.

As for transport protocol, MQTT is what I chose to transport the data. The reason I chose MQTT is because it seems to be the most popular and suitable transport protocol within the topics of ioT and I don't know how it works. Really is curiosity that motivates me towards MQTT. If you want to know how MQTT works, click [**here**](https://mqtt.org/).

This is how MQTT works in my project. The Pycom device acts as a MQTT client that tries to publish the sensor data to the mosquitto MQTT broker under a certain topic every 5 seconds. In the meantime, Telegraph component in the tig-stack acts as a MQTT consumer who subscribes to the same topic so that it can access, collect and process the data that is being published by the Pycom device.

Because we are using WIFI and local server. We really don't need to care about the amount of data being transmitted. The data from the sensor is formatted into a string in json format and json format works very well with the influxDB database in the tig-stack.

### Transmission protocol:
### Transport protocol:

## Prensenting the data

The data is stored in the influxDB component in the tig-stack. It has a retention policy setting that can set how long the data can be stored in the database. But how to set it is beyond my scope. But one thing we know for sure is that the data is stored in the database every 5 seconds.

Grafana component in the tig-stack allows you to easily create and customize your dashboards for visualization. To access Grafana, you need to type http://localhost:3000 in your browser. To correctly configure Grafana, follow [this video ](https://youtu.be/kimH1ENvalg?t=1228).

Voilà! You are done with the whole project. This is how my dashboard looks.

## Finalizing the design

Since this project is a bit of proof of concept, the final product is really simple as you can see from the image below.

To summarize, this simple project really opened my eyes for how to work with hardware and also reminded me that I really should review the basic electrical engineering knowledge since it allows for better understanding of how the micro controller works with the sensors.

This project would have been better if I used the combination of Node-red, InfluxDB and Grafana instead of tig-stack. Node-red provides a flexible and easy-to-use interface and more functioalities to interconnect the broker and the database.

It has been fun to work with this project and it really does not take much time. If you are beginner like me and don't want to get too deep into the jungles of ioT, this project might help you do just that. Have fun!