SYSC3010 Lab4 Mini-Project

This repository was created for Part3 of Lab4 of the SYSC3010 course at Carleton University. The main goals are:

Demonstrate how to build a distributed embedded system using technologies that may be useful for students' own projects
Use git as a Team, where each student changes files in their own branches and then merges their files in the main branch once the new features are implemented.

What does it do?

It allows users to remotely set the LED colors from the SenseHAT attached to a device (RPi).

Technical information

Deployment diagram

DB Schema

Sequence diagram

The scripts

The backend.py

The backend.py script has the Backend() class, which contains all the operations related to the database. For example: setting up users, devices, and configurations, as well as setting up the LED colors. It uses the configuration file (mydbconfig.py) to set and get values from the firebase database.

The device.py

The device.py script should be executed on your RPi. It also interacts with the database using functions defined in backend.py and user configuration information from mydbconfig.py. When you execute the script for the first time, the device and user will be added to the database, and the LED display will be initialized with initial RGB colors.

The next time you execute the device.py script, it will get the color values for the LED display from the database and set the SenseHAT LED display accordingly. While the script is running, it will listen for changes in the database by using firebase streams. In other words, whenever any authorized user changes the LED color using the GUI then a message is received by device.py and the callback function associated with the Firebase stream updates the pixel(s) accordingly.

Authorizing users to control your sense hat LED display

Registered users in the database can be authorized to control your sense hat LED display. In fact, you should give your group mates authorization to control your device. You can achieve this by creating a file with the code below (with their respective emails).

from backend import Backend
from mydbconfig import *
backend = Backend(config, email, firstname, lastname)

# Add each of your group mates
backend.add_authorized_users('my_group_mate1_email@cmail.carleton.ca' )
backend.add_authorized_users('my_group_mate2_email@cmail.carleton.ca' )

The frontend.py

The frontend.py script provides a GUI implemented using dash. Like the device.py script, frontend.py interacts with the database using functions defined in backend.py and user configuration information from mydbconfig.py. When you execute the frontend.py file, a flask server runs in the background (note that dash is built on top of flask, so you will not see the flask code directly). The GUI can be accessed from your local network through the address <frontend_ip>:8050, where frontend_ip is the IP address of the device where the frontend.py script is being executed. It can be run at the same RPi as the device.py script, or on your own computer.

Once you know the IP address of the device where you are running the frontend.py script, you can access it through your local network by typing the URL (<frontend_ip>:8050) in a web browser (from your smartphone, or computer, or through the web browser of your RPi, ...). This is how it will look like if accessed from your smartphone:

Note that the GUI can be run from any computer and can change the LED colors of any device for which the user is authorized. The idea of this project is that any one of your teammates can change the SenseHAT pixels of your RPi.

Install

There are packages required for this mini-project. You can manually install them using the command below, or using bash (from your RPi) using the install.sh script by running the command ./install.sh.

pip3 install pyrebase4 dash dash_daq dash-extensions coloredlogs

Config

To use the Firebase database, you need to first create a Firebase database as performed in Lab3. The schema for the database is shown above and it will be populated automatically when the device.py script is run by each user. Once the database is up and running, you need to provide the configuration information for the database, and for each user. A sample file can be found in here. You should then copy the file

cp dbconfig.py mydbconfig.py

and edit its contents. The file should contain:

Your email
Your firstname
Your lastname
The firebase configuration config

These variables are used by many files and should be set for things to work properly.

The mydbconfig.py file should not be included in the repository since it has sensitive information about user and database. In addition, each student will have in common the config variable (database configuration), but the user information should be different for each student. To avoid pushing the file to your remote repository, just include the file in the .gitignore file. You must create the .gitignore file and add one line for each file to be ignored when pushing local changes to the repo. You can even ignore other directories and patterns in files. For example, the __pycache__ should not be included in your repository. Your .gitignore file will look like this:

mydbconfig.py
*__pycache__*

Deliverables

Student #1

Fork the repository, make it private, add your TA, and the prof
Add collaborators (your group mates)
Configure your repository to enable issues: go to your forked repository 👉 Settings 👉 General 👉 Features 👉 then enable Issues.

Student #2

Create the Firebase real-time database.
Share the connection details with your teammates. They will need this information for their mydbconfig.py files so that their backend.py script knows how to access the shared Firebase real-time DB.

Each student

Setup

Step 1

Create your mydbconfig.py file. It should have the connection configuration information for your team's Firebase database and your own user information (name, email). This file should not be included in the GitHub repository. More information in Config section.

Step 2

Execute the the device.py script on your RPi. The owner of the Firebase database should be able to visualize the new entries in his database. More information about how the device.py script works can be found here.

Step 3

Create a file to give authorization to your group mates to control your Raspberry pi. Each student should have their own file, and it should not be included in your repository. You can execute it as many times as you want, but you only need to do it once (once all users executed Step 2. More information about authorizing other users to control your device can be found above.

Step 4

Execute the frontend.py script to control your authorized devices. Since you executed the device.py script on your RPi, you have at least one device to control. Once your group mates give authorization for you to control their devices, you will see more device options to control.

You can execute this file on your RPi, then verify the RPi IP address, and access it from your computer's web browser using the URL <RPI_IP_address>:8050.

For advanced users 😎

You can execute the frontend.py script from your own computer. To access it from your local network you just need the IP address of your computer instead of the RPi. In addition, you need to install the required packages. The required packages can be found here.

GitHub and git tasks

Open at least 3 issues and assign a label to each
Self-assign issues
Create a new branch to work on the assigned issues
Commit your changes to your current branch
Once the code reflect the solutions, create a pull request to merge with the main branch and resolve the issue.
Before merging the pull request, have at least one teammate review your code. You can discuss any concerns in the pull request discussion on GitHub.

Issues

Capability to erase all LEDs.
- Add a function in the device.py script to continuously check the joystick and set all the values of the LEDs to [0,0,0] if/when the joystick is sense pressed down.
  - Inside this newly created function you should call (clear_leds(device_id)) from the Backend to clear all LEDs. NOT calling the sense.set_pixels(...) function (otherwise the database will not be updated). The device id can be acquired with the function get_device_id(), also from the Backend class.
Add image samples
- Take nice screenshots from your group mates LED screen and add to the images folder.
Update the header/title string in the GUI
- Update the header value from the frontend.py script to be your group name instead of SYSC3010 - Lab4.

will-sloan / L3_G1_Lab4