Introduction: SpeleoSense: Cave Monitoring Device. (MCT Howest)

By
About: Student Multimedia and Creative Technology (MCT) at Howest Kortrijk (Belgium)

For this project, we're making a device that monitors some characteristics of caves, as well as making it easier to keep track of where you've been spelunking. The finished product consists of two devices, connected by a small wire. The first is home to a pressure sensor that keeps track of the narrow passages, which you have to squeeze yourself through. It also has the controls necessary during the activity, like a button to start and stop the expedition, and a button to see the battery percentage of both devices. The second device contains more sensors for temperature, humidity and GPS location, and also houses the raspberry pi, which is the primary controller of the devices and also the keeper of the database and the web app files. When not inside a cave, you can connect to the raspberry pi through your phone or computer and see all the details.

Supplies

For this project you will need:

Components:

  • one Raspberry Pi
  • one Seeed Studios XIAO ESP32-C3
  • one DHT11 temperature and humidity sensor
  • one LCD
  • one NEO-6M GPS module
  • one anti-vandal pushbutton
  • two DS-102R pushbuttons
  • one FSR402 membrane pressure sensor
  • one Adafruit LED strip of 10 LEDs
  • one piezo passive buzzer
  • three 470Ω resistors
  • three 10kΩ resistors
  • one 10Ω resistor
  • one 10kΩ potentiometer

Software:

Note: The instructions are based on these softwares. If you use other software, you will have to search for yourself.

  • Arduino IDE
  • Visual Studio Code
  • MySQL Workbench
  • Win32 Disk Imager
  • VNC viewer
  • Ultimaker Cura
  • a browser

Visual Studio Code Extensions:

  • remote - SSH
  • live sass compiler

Other:

  • two breadboards (optional)
  • Male-to-Female jumper wires
  • Female-to-Female jumper wires
  • one 2 by 20 header stack
  • one 1 by 20 header stack
  • Raspberry Pi power supply
  • USB to USB-C cable
  • Ethernet cable (and ethernet to USB adapter if necessary)
  • a computer
  • a smartphone
  • one micro-SD-card of at least 16GB (and micro-SD to SD adapter if necessary)

For the casing:

  • a 3d-printer

Attachments

Step 1: Preparing the Raspberry Pi

Make sure the Raspberry Pi isn't plugged in until stated otherwise.

  1. Download the Raspberry Pi image. Warning: large file: (2GB).
  2. insert the micro-SD card into your computer.
  3. Open Win32DiskImager.
  4. Select the downloaded file in "Image File".
  5. Select the micro-SD card location in "Device" This looks like "\:D" or another letter that isn't "\:C".
  6. Click "Write". If you get a warning just click "OK". This process can take a few minutes.
  7. When the program is done, safely remove the SD card from your computer.
  8. Make sure the Raspberry Pi is not plugged in.
  9. Insert the SD card into the Raspberry Pi

Step 2: Connecting the Computer to the Raspberry Pi

  1. Connect the Raspberry Pi to your computer using an ethernet cable.
  2. Change the network settings of your ethernet adapter to a static IP address "192.168.168.168" and the Subnet Mask to "255.255.255.0".

Step 3: Assembling the Circuit

Follow the schema to assemble all the components.

It is easier to start the circuit on a breadboard. This allows us to test each component before putting it inside a casing. You can also immediately solder the components.

In the pictures, you can see how I assembled the different components. I secured the antenna of the GPS module underneath the LCD display with isolation tape. The two red wires will connect to the button inside the casing. The yellow wires on the short side of the board are to the ground and 5V. The two yellow wires with red tape are for TX and RXto the esp. The circuit turned out really messy, so following the schemas will be easier.

I also used header stacks to put the circuit onto the raspberry pi and to connect the LCD display.

I used two jumper wires, one male and one female as a connection between the two uart wires. The males are TX to the female RX pins.

After you assembled the circuit, you can plug in the Raspberry Pi.

Step 4: Connecting the Raspberry Pi to the Internet

//TODO: add the username and password

  1. Open VNC Viewer.
  2. Enter "192.168.168.169" into the text field at the top. Then press Enter.
  3. The username is "pi" and the password is "W8w00rd".
  4. A window will open with a desktop. This is the GUI of the Raspberry Pi.
  5. Click the two arrows pointing up and down in the top right corner.
  6. Select the network you want to use and fill in the password.
  7. When the two arrows change into a WiFi symbol, you can close VNC Viewer.

Step 5: Normalized Database

// TODO: add SQL dump file, username, and password

  1. Download the SQL dump file. This is a file that will generate the database with some pre-loaded data on the raspberry pi.
  2. Open MySQL Workbench
  3. Click on the plus icon to add a new connection
  4. Give your connection a useful name
  5. Select the method: Standard TCP/IP over SSH
  6. Type in "192.168.168.169" as the hostname.
  7. Give a good SSH username
  8. Next, add "student" as username and "W8w00rd" as password
  9. After that, you can click ok, and then your new connection is made.
  10. Now open this connection.
  11. Open the downloaded SQL file. This will open in MySQL Workbench.
  12. Copy the insides of this file.
  13. Now open a new SQL file by clicking the first icon in the top left corner.
  14. Paste the insides of the downloaded SQL file and execute the code by clicking the first lightning bolt icon at the top.
  15. If you reload in the "schemas" box, you will now see a new "speleosense" database.

Step 6: Setting Up a Remote SSH Connection in Visual Studio Code

  1. open Visual Studio Code.
  2. with the extension "remote - SSH" installed, you will see a green tile in the bottom left corner. It has two arrows pointing towards each other inside.
  3. Click this tile. A window will appear in the top centre of Visual Studio Code. Choose either "Connect to Host..." or "Connect Current Window to Host...".
  4. Fill in "pi@192.168.168.169".
  5. Fill in the password: "W8w00rd".
  6. Wait until the loading animation in the bottom left corner is finished.

Step 7: Preparing the Files

  1. Click "Clone Git Repository".
  2. copy this link into the window and press enter.
  3. After a short while a window will pop up in the bottom right corner asking to open the repository. Click "Yes".
  4. Now you will see a window with a lot of files. Open the folder "Backend" and then open the file "app.py".
  5. Now open a new terminal by either clicking "Terminal" at the top and then "New terminal" or pressing ctrl+alt+ù.
  6. Now type the following command:
  7. python -m venv .venv
  8. There will appear a window in the bottom right corner, asking to switch to a new environment. Click "Yes".
  9. Now close the terminal and open a new one again. Now the prompt should start with "(.venv)".
  10. Now type the following commands in the terminal. Wait for a new prompt after each one.
  11. sudo apt-get install gpiod libgpiod-dev libgpiod-doc
  12. pip install -r .\requirements.txt
  13. After doing this, create a new file inside the "Backend" folder named "config.py".
  14. Copy the insides of "config_example.py" to this new file.
  15. Change "demo_homecontrol" to "speleosense"
  16. close config.py

Step 8: Enabling the Right Ports

  1. Make sure the terminal is big enough by dragging the top.
  2. type "sudo raspi-config".
  3. A blue window will open inside the terminal. Use your arrow keys and the enter key to navigate.
  4. go to "Interface options" > Serial Port.
  5. For a login shell, select "no" and press enter.
  6. For the port hardware, select "yes" and press enter.
  7. select "ok".
  8. Navigate to "Finish" by using the right arrow key and exit raspi-config. You will now be back in the terminal.

Step 9: The Backend

The backend is coded in Flask, a server package for Python. "app.py" is the main file, which consists of two large sections. The first section controls the gpio pins, which means controlling all the components, reading all the sensors, communicating with the esp and saving values to the database.

The second part is responsible for providing the data to the web server. It is made up of routes that the frontend can use to get all the data. It also has some socket io, which is an extension of Flask meant for real-time communication between the front and backend.

GPIO pins

First, they communicate with the DHT sensor using the Adafruit library. This reads serial data from the sensor and performs an algorithm on the incoming data and returns the temperature and humidity.

second, the GPS module is read through the GPS class inside "GPS.py". This is done through the serial uart interface on the Pi.

The LCD screen is controlled through "LCD.py". This file gives us simple commands to effectively control what is displayed.

There is also a class for a button, which simplifies reading when it is pressed.

Finally, there is a class to communicate with the esp. It contains a way to send messages and automatically inserts a prefix which the esp interprets to eliminate wrong messages.

Flask: Routes

There are routes for practically everything that can be done with the data, which allows for complete control of the database from the web server. You can create, read, update and delete both caves and expeditions,and there are routes to start and stop expeditions, as well as some quick routes to do specific things.

Flask: SocketIO

The live data is only needed on the home page. There are events for when the app connects, for when it asks for both temperature and humidity and to get the battery percentages of the devices, as well as updating the log, which is only displayed on a desktop screen.

Step 10: The Frontend

For the frontend, there are 4 pages. the home page, an overview of expeditions and caves, and a detail page for each expedition and cave. The data is received from the backend and nicely cast into a structure that the site can read by javascript. The javascript also controls the things like the notes on the log table. For the layout and style, I use a boilerplate provided in SCSS, and added a lot of custom components as well.

Step 11: Good Luck