Terminarium

Table of Contents

• Terminarium
  • Table of Contents
  • Synopsis & Motivation
  • Dependencies & Requirements
  • Installation
    • Installation Process - Wio Terminal
    • Web-based Application - Local Installation
  • Usage
    • Wio Terminal - Usage
      • 1. Arduino IDE - Usage
      • 2. Automated Shell Script - Usage
    • Web-based Application - Live Demo
    • Web-based Application - Local Usage
    • Demo and Examples
  • System design
  • Acknowledgements
  • Contributing
  • License
    • Team members

The project is entitled "Terminarium", a portmanteau derived from the words Terrarium and Terminal that represents the interplay between the physical components of our integrated system; environmental data is collected from within a terrarium physical sensors that are connected to a terminal

Synopsis & Motivation

The project is an all-in-one integrated system for monitoring the environment of terrariums and other kinds of bioactive enclosures. Through the use of sensors contained in the enclosure and connected to a terminal, environmental measurements are conveyed to a web-based user interface which communicates both raw and processed data and analytics. This will enable users to stay informed about the conditions of their terrarium remotely.

Furthermore, the system will notify the user in the event of an emergency where environmental conditions fall outside of desired limits. These can either be user-defined or based on a specific preset. The system is designed to be easily expandable and customizable to fit the needs of the user.

Dependencies & Requirements

The following section lists the dependencies and requirements for the project; these should be installed prior to the installation process described in the section afterwards.

1. Wio Seeed Terminal (or compatible alternative board)
2. Arduino IDE or Arduino CLI (optional: for CLI usage)
3. Wio Terminal Board Library (parsed from link); more information can be found here
4. A collection of Arduino libraries$^*$:
   • DHT-Sensors-Non-Blocking library, Toan Nguyen
   • TFT_eSPI, Bodmer
   • rpcWifi, Hontai Liu / Seeed
   • PubSbClient, Nick O'Leary
   • FlashStorage_SAMD, Khoih Prog & Cristian Maglie
5. Wio Terminal Grove Sensors:
   • the list of the required sensors can be obtained from link.
6. Node.js and npm (the Node Package Manager) for the web-based application (it is required to go with the latest stable version of Node.js)
   • Node.js comes pre-packaged with npm, so there's no need to install npm separately.
   • All the required dependencies for the web-based application are listed in the package.json file and no additional packages and/or global dependencies are required to be installed.
7. Git is required to be installed in order to clone the repository

$^*$Note: despite our best efforts, we were unable to find a solution how to automate the process of installing the required Arduino libraries. Therefore, the user is required to install the libraries manually via the Arduino IDE. For additional guidance, please refer to the Arduino Library Manager documentation.

Installation

The following sections contains the required steps of the installation process.

Installation Process - Wio Terminal

As indicated previously, the required libraries are to be installed manually via the Arduino IDE. The following steps are required to install the libraries:

1. Open the Arduino IDE and navigate to Tools > Manage Libraries...
2. Install the required libraries by searching for the library name (from the list Dependencies & Requirements point 4) in the search bar and clicking on the Install button.
   • It is recommended to download the latest version of the library.

Web-based Application - Local Installation

Our project makes use of Node.js and npm (the Node Package Manager) to install the required dependencies for the web-based application. The following steps are required to install the dependencies:

# Assuming that the user is in the root directory of the project
# and cloned the repository with the following command: 
git clone <repository-url>

# 0. Navigate to the source of the website
cd src/web/terminarium-web

# 1. Install all the required dependencies
npm install

However, there's an extra step required in order to make use of Firebase Realtime Database. In short, an .env file is to be created in the src/web/terminarium-web directory with the following contents:

# .env file - access to the Firebase Realtime Database
VITE_API_KEY="<API_KEY>"
VITE_AUTH_DOMAIN="<AUTH_DOMAIN>"
VITE_DATABASE_URL="<DATABASE_URL>"
VITE_PROJECT_ID="<PROJECT_ID>"
VITE_STORAGE_BUCKET="<STORAGE_BUCKET>"
VITE_MESSAGING_SENDER_ID="<MESSAGING_SENDER_ID>"
VITE_APP_ID="<APP_ID>"
VITE_MEASUREMENT_ID="<MEASUREMENT_ID>"

These credentials can be obtained from the Firebase Console.

Miscellaneous

By having the .env file in place, the web-based application will be able to connect to the Firebase Realtime Database, and thus, the user will be able to view the data that is being collected from the sensors, and so on.

Observe: Vite.js is responsible for distributing the env variables, and no external packages are required to be installed in order to make use of the .env file. For more information, please refer to the Vite.js documentation.

Usage

Wio Terminal - Usage

There's two main ways how to get started with the Wio Terminal with our project and they are covered in this subsection.

1. Arduino IDE - Usage

Having followed the Installation Process section, the user can simply:

1. Open the Arduino IDE and navigate to File > Open...
2. Open the terminarium folder (src/wio/terminarium) and select the terminarium.ino file from the directory
3. Upload the sketch to the Wio Terminal by clicking on the Upload button
   1. The Wio Terminal is required to be connected to the computer via the USB cable
   2. To open the Serial Monitor, navigate to Tools > Serial Monitor and select the 9600 baud option.

2. Automated Shell Script - Usage

Who loves automation? We do! Therefore, we have created a shell script which is a wrapper for the Arduino CLI and it is located in the src/sh directory. The following steps are required to run the script:

# 0. Navigate to the source from the root
cd src/

# 1. View the usage of the script (help flag)
./sh/terminarium.sh -h 
./sh/terminarium.sh --help

Usage: terminarium.sh [port] [+options]
  port: the port where the Arduino board is connected to
  options:
    --list-ports, -lp: list all the available ports
    --help, -h: show the usage

# 2. List all the available ports
./sh/terminarium.sh -lp
./sh/terminarium.sh --list-ports

# 3. Run the script with the desired port destination
#   (the port is required to be connected to the computer)
#   (replace <XXXX> with the port number obtained from the previous step)
./sh/terminarium.sh /dev/cu.usbmodem<XXXX>

# 4. To stop the script, press CTRL + C in the terminal
# 5. Enjoy!

Furthermore, this script emulates the Serial monitor right in your terminal instance. Therefore, the user is able to view the data that is being collected from the sensors, and so on. Is that not cool? We think it is!

Note: the following script is only available for Unix based systems, such as Linux and macOS. However, the script can be easily modified to work with Windows based systems.

Web-based Application - Live Demo

The website application is deployed via Netlify; a report of the deployment can be found here.

Web-based Application - Local Usage

There's an opportunity to run the web-based application locally. The following steps are required to engage with the application locally:

# Assuming that the user is terminarium-web directory
# 0. Navigate to the source of the website
cd src/web/terminarium-web

# 1. Run the application locally
npm run dev

# 2. Open the browser with the localhost:XXXX address
#    (the port number is displayed in the terminal)

# 3. To stop the application, press CTRL + C in the terminal

Additional Utilities

All the additional commands, such as for testing, linting, etc. can be found in the package.json file.

Demo and Examples

As part of the project's delivery, the following video was created to demonstrate the core functionality of the system:

Terminarium - Project Demo

Terminarium CLI Demo

The following video demonstrates the usage of the Terminarium CLI:

Terminarium CLI - Demo

System design

The system's design is depicted in the following diagram (with an additional legend):

*view the diagram in an uncompressed form (full quality): link

Acknowledgements

Contributors: refer to the section 'Team Members' for more information.

Frameworks and open-source libraries:

• Vue.js: Credits to the authors and maintainers of the Vue.js framework. Vue facilitated the tools we needed to develop the UI for the project. Similarly, to Node.js and npm (the Node Package Manager) for the web-based application.
• Firebase Realtime Database by Firebase Inc.
• Credit it due to the authors and maintainers of the open-source libraries used in the project regarding the Wio Terminal and Arduino programming.

Additional acknowledgements

Sponsors:

We would like to acknowledge University of Gothenburg | Chalmers for supplying hardware and other resources for the project.

Special thanks:

To TAs (Teaching Assistants), Amin Mahmoudifard and Bao Quan Lindgren, we pay special tribute for providing guidance and wisdom throughout the development experience.

Contributing

The contributing guidelines for the Terminarium project should be adhered to by all contributors as specified by the guidelines in the document: CONTRIBUTING.md.

License

The license of the project is to be added once it has been released as an open-source repository to a public platform (i.e. GitHub).

Team members

• Manely Abbasi (@manely): Made significant contributions to User Interface (UI) development and the design of the Website-based application.
• Erik Lindstrand (@elindstr): Made significant contributions to the User Interface (UI) development of the Website-based application.
• Michal Spano (@spano): Provided extensive knowledge in project development and led the team as project manager. Michal supervised and contributed across the whole system on both the hardware and software side.
• James Klouda (@klouda): Made significant contributions to the User Interface (UI) development of the Website-based application.
• Konstantinos Rokanas (@rokanas): Made significant contributions to the Back-End with a special focus on the Wio terminal.
• Jonathan Boman (@bomanjo): Made significant contributions to the Back-End utilities related to the Wio terminal and the Website-based application.

The team members have used the following CODE_OF_CONDUCT.md file as a reference: link.

---

Terminarium 2023, DIT113, University of Gothenburg | Chalmers University of Technology, Sweden