Browse Source
commitmastere23be46f54Author: Craig Oates <craig@craigoates.net> Date: Fri Nov 5 16:59:01 2021 +0000 update Midpoint doc. commit70e23d0902Author: Craig Oates <craig@craigoates.net> Date: Fri Nov 5 16:55:27 2021 +0000 update Midpoint doc. commit3daa38662aAuthor: Craig Oates <craig@craigoates.net> Date: Fri Nov 5 16:46:04 2021 +0000 update README doc. commit2e9d1df94dAuthor: Craig Oates <craig@craigoates.net> Date: Fri Nov 5 16:19:39 2021 +0000 create and populate Light Wave doc. commit73464777feAuthor: Craig Oates <craig@craigoates.net> Date: Thu Nov 4 20:34:37 2021 +0000 add Return to Ritherdon Project Overview .dot file. This is the file used to generate the .png version of the file in the main README.md file. commit76710d26cbAuthor: Craig Oates <craig@craigoates.net> Date: Thu Nov 4 20:32:30 2021 +0000 update README doc. diagrams. I added a .dot file for the Return to Riterdon project overview and fix the image links for so the diagrams sit in their correct places within the document. commit131bdefdc3Author: Craig Oates <craig@craigoates.net> Date: Thu Nov 4 20:27:49 2021 +0000 add .dot file for diagram in README. This is the file used to illustrate the how 'Personal Flash in Real-Time' fits into the 'Return to Ritherdon' project. commit6dae2040dcAuthor: Craig Oates <craig@craigoates.net> Date: Thu Nov 4 20:27:27 2021 +0000 update README doc (main project overview). commitd20d592495Author: Craig Oates <craig@craigoates.net> Date: Thu Nov 4 19:39:12 2021 +0000 update Midpoint doc. commitdb74ec5d06Author: Craig Oates <craig@craigoates.net> Date: Thu Nov 4 19:14:05 2021 +0000 populate midpoint doc. commita4ecffeec9Author: Craig Oates <craig@craigoates.net> Date: Wed Nov 3 20:31:37 2021 +0000 start populating Midpoint doc. This is a work in progress (end of session) commit. commitbf8a961f99Author: Craig Oates <craig@craigoates.net> Date: Wed Nov 3 20:02:07 2021 +0000 fix typo in Relay doc. commit8902037b83Author: Craig Oates <craig@craigoates.net> Date: Wed Nov 3 19:53:14 2021 +0000 update Relay doc. commit0e62c64f06Author: Craig Oates <craig@craigoates.net> Date: Tue Nov 2 19:00:20 2021 +0000 stub out further sections for Relay doc. This is prep. work for expanding the documentation for the Relay project. End of session commit, though, which is the reason why the sections are not filled out. commitaf03002f48Author: Craig Oates <craig@craigoates.net> Date: Tue Nov 2 18:50:31 2021 +0000 populated Relay doc. This is a rough transfer of my personal notes in to the public doc's for the Relay project. I've not gone through it properly so expect mistakes and it needing a good proof-read. commitc8eba160fbAuthor: Craig Oates <craig@craigoates.net> Date: Tue Nov 2 18:07:02 2021 +0000 update Light Meter doc. commit755db34e92Author: Craig Oates <craig@craigoates.net> Date: Tue Nov 2 17:52:21 2021 +0000 update light-meter doc. commitd28dea87c4Author: Craig Oates <craig@craigoates.net> Date: Tue Nov 2 17:15:13 2021 +0000 add install section to Eyes and Ears doc. commitd5e6440297Author: Craig Oates <craig@craigoates.net> Date: Tue Nov 2 17:09:27 2021 +0000 add links to other projects (Eyes and Ears doc's). commit5b2583c00bAuthor: Craig Oates <craig@craigoates.net> Date: Tue Nov 2 16:59:32 2021 +0000 populate the Eyes and Ears section. commitb3408532d8Author: Craig Oates <craig@craigoates.net> Date: Tue Nov 2 12:57:48 2021 +0000 change Ross to Andy. At some point, I forgot when it was, Ross was replaced by Andy as a welder. This name change is just me dotting the i's and crossing the t's.
31 changed files with 1065 additions and 114 deletions
@ -0,0 +1,14 @@
|
||||
digraph overview { |
||||
node [fontname = Arial]; |
||||
l1 -> server; |
||||
l2 -> server; |
||||
server -> r1; |
||||
server -> r2; |
||||
r1 -> server; |
||||
r2 -> server; |
||||
l1 [label = "Light Meter 1", color = lightblue, style = filled]; |
||||
l2 [label = "Light Meter 2", color = orange, style = filled]; |
||||
r1 [label = "Relay 1", color = lightblue, style = filled]; |
||||
r2 [label = "Relay 2", color = orange, style = filled ]; |
||||
server [label = "Midpoint (Server)"]; |
||||
} |
||||
|
Before Width: | Height: | Size: 190 KiB After Width: | Height: | Size: 25 KiB |
@ -0,0 +1,29 @@
|
||||
digraph overview { |
||||
fontname = Arial; |
||||
node [fontname = Arial]; |
||||
label = "Return to Ritherdon"; |
||||
labelloc = top; |
||||
style = filled; |
||||
color = lightgrey; |
||||
fontsize = 20; |
||||
subgraph cluster0 { |
||||
style = filled; |
||||
node [style = filled, color = white]; |
||||
color = lightblue; |
||||
label = "Personal Flash in Real-Time (I.E. 'Artwork 1')"; |
||||
fontsize = 16; |
||||
Light; |
||||
Midpoint; |
||||
Relay; |
||||
} |
||||
subgraph cluster1 { |
||||
label = "The other artworks in the exhibiton/project..."; |
||||
fontsize = 16; |
||||
color = white; |
||||
style = filled; |
||||
a5 [label = "Artwork 5"]; |
||||
a4 [label = "Artwork 4"]; |
||||
a3 [label = "Artwork 3"]; |
||||
a2 [label = "Artwork 2"]; |
||||
} |
||||
} |
||||
|
Before Width: | Height: | Size: 79 KiB After Width: | Height: | Size: 26 KiB |
@ -0,0 +1,17 @@
|
||||
digraph overview { |
||||
fontname = Arial; |
||||
labelloc = t; |
||||
label = "Eyes and Ears"; |
||||
fontsize = 20; |
||||
node [fontname = Arial]; |
||||
MainPage -> ViewModel -> Services; |
||||
ViewModel -> MainPage; |
||||
Services -> ViewModel; |
||||
MainPage -> Services; |
||||
Services -> MainPage; |
||||
Models -> ViewModel; |
||||
Models -> MainPage; |
||||
Models -> Services; |
||||
MainPage [style = filled, color = lightblue, label="MainPage (View and Code-Behind)"]; |
||||
ViewModel [label = "ViewModels/MainPageVM"]; |
||||
} |
||||
|
After Width: | Height: | Size: 45 KiB |
|
After Width: | Height: | Size: 719 KiB |
|
After Width: | Height: | Size: 687 KiB |
|
After Width: | Height: | Size: 3.9 MiB |
@ -0,0 +1,21 @@
|
||||
digraph overview { |
||||
subgraph cluster0 { |
||||
label = "Main System"; |
||||
fontname=Arial; |
||||
fontsize=20; |
||||
node [style=filled,color=white,fontname=Arial]; |
||||
style=filled; |
||||
color=lightblue; |
||||
l1 -> Server -> r1; |
||||
l2 -> Server -> r2; |
||||
r1 -> Server; |
||||
r2 -> Server; |
||||
l1 [label = "Light Meter 1"]; |
||||
l2 [label = "Light Meter 2"]; |
||||
r1 [label = "Relay 1"]; |
||||
r2 [label = "Relay 2"]; |
||||
} |
||||
e -> Server; |
||||
Server -> e; |
||||
e [label = "Eyes and Ears",fontname=Arial;]; |
||||
} |
||||
|
After Width: | Height: | Size: 29 KiB |
@ -0,0 +1,20 @@
|
||||
digraph overview { |
||||
node [fontname = Arial]; |
||||
subgraph cluster0 { |
||||
style = filled; |
||||
color = lightgrey; |
||||
l1; |
||||
l2; |
||||
} |
||||
l1 -> server; |
||||
l2 -> server; |
||||
server -> r1; |
||||
server -> r2; |
||||
r1 -> server; |
||||
r2 -> server; |
||||
l1 [label = "Light Meter 1", color = lightblue, style = filled]; |
||||
l2 [label = "Light Meter 2", color = orange, style = filled]; |
||||
r1 [label = "Relay 1", color = lightblue, style = filled]; |
||||
r2 [label = "Relay 2", color = orange, style = filled ]; |
||||
server [label = "Midpoint (Server)"]; |
||||
} |
||||
|
Before Width: | Height: | Size: 190 KiB After Width: | Height: | Size: 23 KiB |
|
After Width: | Height: | Size: 54 KiB |
@ -0,0 +1,66 @@
|
||||
# Return to Ritherdon: Light Wave |
||||
|
||||
This is a support project to help test and monitor the Light Meter in |
||||
the factory (Ritherdon). It provide about a minutes worth of streamed |
||||
light readings from the facory and displays both readings as animated |
||||
line graph. When the exhibition is live, the intention is for it to |
||||
provide additional information in the gallery space (I.E. Castlefield |
||||
Gallery) for the viewers. |
||||
|
||||
For more information about the 'Return to Ritherdon' project, please |
||||
you the links below: |
||||
|
||||
- [Light Meter Code](https://git.abbether.net/return-to-ritherdon/light-meter) |
||||
- [Light Meter Documentation](https://git.abbether.net/return-to-ritherdon/rtr-docs/src/branch/master/light-meter) |
||||
- [Relay Code](https://git.abbether.net/return-to-ritherdon/relay) |
||||
- [Relay Documentation](https://git.abbether.net/return-to-ritherdon/rtr-docs/src/branch/master/relay) |
||||
- [Midpoint Code](https://git.abbether.net/return-to-ritherdon/midpoint) |
||||
- [Midpoint |
||||
Documentation](https://git.abbether.net/return-to-ritherdon/rtr-docs/src/branch/master/midpoint) |
||||
|
||||
They will provide a much broader overview of how the various parts and |
||||
projects fit together. Because Light Wave is a support project, there |
||||
is no distinct connection between this project and the three main ones |
||||
(I.E. Light Meter, Relay and Midpoint). |
||||
|
||||
 |
||||
|
||||
This program is set-up as a glorified script (all in one file). So, |
||||
there is not much to document. Essentially, all the main code resides |
||||
in `light-wave.py` which you can read by clicking the link below: |
||||
|
||||
- [light-wave.ph](https://git.abbether.net/return-to-ritherdon/light-wave/src/branch/master/light-wave.py) |
||||
|
||||
## Project Set-up |
||||
|
||||
This assumes you are on a Linux (Debian/Ubuntu based) machine. Because |
||||
of project constraints, other environments have not been tested. |
||||
|
||||
```bash |
||||
# Clone repo. if you haven't already. |
||||
git clone http://git.abbether.net/return-to-ritherdon/light-wave.git |
||||
cd light-wave |
||||
|
||||
# Create and activate the virtual environment |
||||
python3 -m venv venv |
||||
source venv/bin/activate |
||||
|
||||
# Install dependencies (with pip) |
||||
pip install -r requirements.txt |
||||
|
||||
# Run the program |
||||
python light-wave.py |
||||
``` |
||||
|
||||
**You might need to add additional packages (via `apt`)**. The most |
||||
notable reason why is because Matplotlib needs some extra things to |
||||
run. It looks like the list depends on what you've already installed |
||||
on your system -- I've only checked Debian. Use the following link for |
||||
more information about installing stuff more Matplotlib: |
||||
|
||||
- [Matplotlib Install Notes](https://matplotlib.org/stable/users/installing.html) |
||||
|
||||
There is not much more to say on this one. It is basically a script |
||||
gluing the various parts of Matplotlib together. If you would like to |
||||
extend this program, you will need to use the Matplotlib link above |
||||
and learn more about how that works. |
||||
@ -0,0 +1,19 @@
|
||||
digraph overview { |
||||
node [fontname = Arial]; |
||||
l1 -> server; |
||||
l2 -> server; |
||||
server -> r1; |
||||
server -> r2; |
||||
r1 -> server; |
||||
r2 -> server; |
||||
l1 [label = "Light Meter 1", color = lightblue, style = filled]; |
||||
l2 [label = "Light Meter 2", color = orange, style = filled]; |
||||
r1 [label = "Relay 1", color = lightblue, style = filled]; |
||||
r2 [label = "Relay 2", color = orange, style = filled ]; |
||||
subgraph cluster0 { |
||||
style = filled; |
||||
color = lightgrey; |
||||
server; |
||||
} |
||||
server [label = "Midpoint (Server)", style = filled, color = white]; |
||||
} |
||||
|
After Width: | Height: | Size: 24 KiB |
|
After Width: | Height: | Size: 56 KiB |
@ -0,0 +1,331 @@
|
||||
# Return to Ritherdon: Midpoint |
||||
|
||||
Midpoint is one of three smaller projects which make-up 'Personal |
||||
Flash in Real-Time' -- which is one artwork within the main 'Return to |
||||
Ritherdon' project. You should view the three smaller projects as one |
||||
project. And, for the purpose of this documentation, I will refer to |
||||
'Personal Flash in Real-Time' as a system instead of an artwork. |
||||
|
||||
For more information on the 'Return to Ritherdon' project, use the |
||||
following link: |
||||
|
||||
- [Return to Ritherdon Overview](https://git.abbether.net/return-to-ritherdon/rtr-docs) |
||||
|
||||
## 'Personal Flash in Real-Time': Project Overview |
||||
|
||||
The overall system ('Personal Flash in Real-Time') consists of three |
||||
separate/smaller projects. You should not view them as individual |
||||
pieces within the overall project. From an artwork point-of-view, |
||||
'Personal Flash in Real-Time' is one piece. The name of the software |
||||
projects are 'Light Meter' (which is this one), 'Midpoint' and |
||||
'Relay'. All three projects reside in their own git repositories. You |
||||
can find the repositories at the following links: |
||||
|
||||
- [Light Meter](https://git.abbether.net/return-to-ritherdon/light-meter) |
||||
- [Mid-Point](https://git.abbether.net/return-to-ritherdon/midpoint) |
||||
- [Relay](https://git.abbether.net/return-to-ritherdon/relay) |
||||
|
||||
The (technical) aim of the project is to turn a set of lights on at |
||||
the gallery when the welding machines are active in the welding booths |
||||
at Ritherdon. The solution we arrived at was a three-stage |
||||
process. The stages are as follows: |
||||
|
||||
1. Monitor the light levels in the welding booths at Ritherdon and |
||||
send that information to a sever (Light Meter). |
||||
2. Receive the light readings and store them in a database and make |
||||
them available for others to access (Midpoint). |
||||
3. Have the lights installed at the gallery connected to wi-fi enabled |
||||
relays which request the latest light readings from the server. If |
||||
the readings are above a certain threshold, have the light in the |
||||
gallery turn on (otherwise, turn off). The relays are responsible |
||||
for turning the lights on and off (Relay). |
||||
|
||||
Each step should require no human intervention. |
||||
|
||||
For more information on how each project accomplishes its task, please |
||||
use the (repo.) links above. Otherwise, here is an diagram to help |
||||
explain the three stages mentioned above. |
||||
|
||||
 |
||||
|
||||
## Hardware Specifications |
||||
|
||||
There are no specific hardware requirements. If you can get an machine |
||||
to run a server (E.G. Nginx or Apache), you should be good to |
||||
go. Unfortunately, the scope of the project meant the amount of |
||||
support for hardware and software is limited to an x86 Linux based |
||||
machine running Nginx. I decided to run a virtual machine on Amazon |
||||
Web Services. |
||||
|
||||
- [Amazon Web Services](https://aws.amazon.com/) (A.W.S.) |
||||
|
||||
## Software Requirements |
||||
|
||||
I have set-up the server to run on Linux (I.E. Ubuntu) with an Nginx |
||||
server -- on an x86 machine. Any other variation on that |
||||
(I.E. Windows), you will be on your own. The reason why is because I |
||||
have not tested it. How you acquire the hardware is up to you. For the |
||||
intents of the project, I used a virtual machine on Amazon Web |
||||
Services. Links for various parts of the set-up are below: |
||||
|
||||
- [https://ubuntu.com/](https://ubuntu.com/) |
||||
- [Nginx](https://www.nginx.com/) |
||||
- [Python Flask](https://flask.palletsprojects.com/en/2.0.x/) |
||||
- [Gunicorn](https://gunicorn.org/) |
||||
- [Supervisor](https://pypi.org/project/supervisor/) (Python) |
||||
- [SQLite Database](https://sqlite.org/index.html) |
||||
- [SQL Alchemy](https://www.sqlalchemy.org/) (O.R.M.) |
||||
- [Swagger REST API](https://swagger.io/) |
||||
|
||||
## Software Set-up |
||||
|
||||
Below is an overview of the files and directory structure. |
||||
|
||||
```shell |
||||
app/ |
||||
├── api.py <-------- REST API entry point. |
||||
├── app.py <------- 'Main' program entry point. |
||||
├── build_database.py <-- Builds database (use first). |
||||
├── config.py <----- Program config's for Flask and Swagger. |
||||
├── models <-------- Objects which database rows are mapped to. |
||||
├── __pycache__ |
||||
├── readings.db <--- The SQLite database. |
||||
├── services <------ 'Business logic' for api.py entry points. |
||||
├── static <------- Images/Favicons/Style Sheets. |
||||
├── swagger.yml <--- YAML config. file for Swagger (REST API). |
||||
└── templates <----- HTML views. |
||||
``` |
||||
|
||||
### The Program (Python and Virtual Environment) |
||||
|
||||
**I have omitted instructions on creating user accounts beyond the |
||||
defaults** because that comes with a fair bit of context specific |
||||
information which is beyond the scope of this documentation. On top of |
||||
that, the project's budget did not allow for extended research on |
||||
various Cloud Platforms and server architecture, in-general. |
||||
|
||||
After you have established a V.M. on A.W.S. or your own server, you |
||||
will need to clone the repository (**I am assuming this is via SSH**). |
||||
|
||||
```bash |
||||
# Adjust the directories to how you prefer it. These are just my defaults. |
||||
mkdir www |
||||
cd www |
||||
git clone http://git.abbether.net/return-to-ritherdon/midpoint.git |
||||
cd midpoint |
||||
``` |
||||
|
||||
From there, you can create a Python virtual environment if you prefer |
||||
to keep things isolated. You can ignore the virtual environment step |
||||
and install the requirements at a system-wide level. If you do that, |
||||
you will need to use `pip3` instead of `pip`. |
||||
|
||||
```bash |
||||
# Adjust the path to suit to environment. |
||||
python3 -m venv ~/repos/midpoint/venv |
||||
|
||||
# Install the requirements... |
||||
(use pip3 if you're not using a virtual environment) |
||||
pip install -r requirements.txt |
||||
``` |
||||
|
||||
As an aside, I created a virtual environment with `python3 -m venv |
||||
~/www/midpoint/my-env` whilst in development. This environment might |
||||
still be around the production server, used during the |
||||
exhibition. **If you are completing a fresh install, this is not |
||||
relevant to you. Please ignore.** |
||||
|
||||
|
||||
### The Server |
||||
|
||||
The host name for the server used during the exhibition was |
||||
`piapi`. So, I will use that in the documentation below. **Please make |
||||
sure you replace `piapi` with the host name you are using.** |
||||
|
||||
I used Nginx and Gunicorn for the exhibition so that is all this |
||||
documentation will focus on. Midpoint should work on other servers |
||||
(like Apache) but I have not tested it. |
||||
|
||||
The Nginx configuration file is located at: |
||||
|
||||
- `/etc/nginx/sites-enabled/piapi` |
||||
|
||||
You can access the file with `sudo nano |
||||
/etc/nginx/sites-enabled/piapi` when logged into the server. |
||||
|
||||
Because Nginx is responsible for the static side of the website, |
||||
Gunicorn is needed to operate the Python side of it. Nginx knows |
||||
how/when to pass control over to Gunicorn because it is configured in |
||||
the … sites-enables/piapi configuration file (mentioned above). With |
||||
that said, Gunicorn still needs to be set-up for everything to run |
||||
properly. It is worth pointing out, the "static" part of the site will |
||||
still run when Gunicorn is not running but that is a practically |
||||
useless feature. To run Gunicorn, enter the following command into the |
||||
terminal (of logged in V.M), |
||||
|
||||
```bash |
||||
# You can adjust the '-w 3' if you have a more powerful server. Also, |
||||
the 'connext_app' related to the use of the Swagger API code. |
||||
gunicorn -w 3 server:connex_app |
||||
``` |
||||
|
||||
The `-w 3` bit refers to the total number of workers (processors) |
||||
Gunicorn will use whilst running. The general rule to work that out it |
||||
/(number of processors * 2) + 1. At the time of writing, the virtual |
||||
machine used for the exhibition is a very basic one-core machine so |
||||
that is why three workers is used. |
||||
|
||||
One problem with Gunicorn is it blocks the terminal when using it in |
||||
its default way. To get around this, I have install Supervisor to |
||||
manage it. Supervisor handles the auto-restart after a crash and |
||||
background-task management of it too. To install it, run the following |
||||
command, |
||||
|
||||
```bash |
||||
sudo apt install supervisor |
||||
``` |
||||
|
||||
When Supervisor is installed, you need to create a config. file. The |
||||
file for this project is stored at, |
||||
|
||||
- `/etc/supervisor/conf.d/spiapi.conf` |
||||
|
||||
The log files (specified in the .conf) file are, |
||||
|
||||
- `/var/log/midpoint/midpoint.err.log` |
||||
- `/var/log/midpoint/midpoint.out.log` |
||||
|
||||
You will need to recreate the directory they are stored in if you are |
||||
installing this site on a new system. The easiest way to do that is to |
||||
run the following command, |
||||
|
||||
```bash |
||||
sudo mkdir -p /var/log/midpoint |
||||
sudo touch /var/log/midpoint/midpoint.err.log |
||||
sudo touch /var/log/midpoint/midpoint.out.log |
||||
``` |
||||
|
||||
When you have finished making these changes, you will need to restart |
||||
Supervisor. To do that, run the following command, |
||||
|
||||
```bash |
||||
sudo supervisor reload |
||||
``` |
||||
|
||||
It might take a little while for the service to restart so if you |
||||
still see "Bad Gateway" messages in the browser, that might be why. |
||||
|
||||
You might find Gunicorn is not installed in the virtual-environment |
||||
(if you have decided to not install one or you simply forget to |
||||
activate like I have a habit of doing), it that is the case, you |
||||
should find it at, |
||||
|
||||
- `home/ubuntu/.local/bin/gunicorn` |
||||
|
||||
This might, also, mean you need to use `apt` and not `pip3`. |
||||
|
||||
The config. file for Supervisor should look something like the |
||||
following, (remember to adjust the places where `ubuntu` is with your |
||||
servers account name -- if it differs from `ubuntu`) |
||||
|
||||
```bash |
||||
[program:midpoint] |
||||
directory=/home/ubuntu/www/midpoint/app |
||||
command=/home/ubuntu/.local/bin/gunicorn -w 3 server:connex_app |
||||
user=ubuntu |
||||
autostart=true |
||||
autorestart=true |
||||
stopasgroup=true |
||||
killasgroup=true |
||||
stderr_logfile=/var/log/midpoint/midpoint.err.log |
||||
stdout_logfile=/var/log/midpoint/midpoint.out.log |
||||
``` |
||||
|
||||
The config. file for Nginx should look like the following, |
||||
|
||||
```bash |
||||
server { |
||||
listen 80; |
||||
server_name 35.176.235.94; |
||||
|
||||
location /static { |
||||
alias /home/ubuntu/www/midpoint/app/static; |
||||
} |
||||
|
||||
location / { proxy_pass http://localhost:8000; include |
||||
/etc/nginx/proxy_params; proxy_redirect off; } } |
||||
``` |
||||
|
||||
**I did not set-up the server to use HTTPS because it was outside the |
||||
scope of the project.** Again, replace `ubuntu` with your servers |
||||
username. |
||||
|
||||
### Flask & Swagger |
||||
|
||||
To access the A.P.I. user-interface (via Swagger), enter |
||||
|
||||
-`http://0.0.0.0:5000/api/ui/` |
||||
|
||||
- [Real Python](https://realpython.com/flask-connexion-rest-api/#using-connexion-to-add-a-rest-api-endpoint) |
||||
|
||||
Real Python provides a good walk-through for setting-up a website using |
||||
the Flask framework. Real Python, also, provides guides on creating |
||||
websites with Python and its various website frameworks. |
||||
|
||||
I have imported the `connexion` project into this one. By doing this, |
||||
I can use Swagger and its U.I. When you have the server running, go to |
||||
`localhost:5000/api/swagger`. When there, you can test the A.P.I. out |
||||
by sending it "gets" and "posts". |
||||
|
||||
 |
||||
|
||||
The Swagger endpoint are configured in a YAML file at, |
||||
|
||||
- [midpoint/app/swagger.yml](https://git.abbether.net/return-to-ritherdon/midpoint/src/branch/unstable/app/swagger.yml) |
||||
|
||||
### Database and O.R.M. |
||||
|
||||
The project uses a SQLite database to store light reading and any |
||||
device status updates. To write to the database, I used SQL Alchemy as |
||||
a Object Relational Mapper (O.R.M). The database is called, |
||||
|
||||
- `readings.db` |
||||
|
||||
Before you can start the program, you will need to build the |
||||
database. To do that, you will need to run the following commands, |
||||
|
||||
```bash |
||||
# Make sure you are in the 'app' directory. Adjust the 'cd' path to |
||||
# match your set-up. |
||||
cd ~/www/midpoint/app/ |
||||
|
||||
# If you have created and activated a virtual environment, you can |
||||
# enter 'python' instead of 'python3'. |
||||
python3 build-database.py |
||||
``` |
||||
|
||||
This will clear the database if one is already set-up and then build a |
||||
new one. |
||||
|
||||
## Notes on System Limitations |
||||
|
||||
### 1. Connection Times-Out on Large JSON Packets |
||||
|
||||
The biggest thing to remember the REST API calls which grab 'all' the |
||||
light readings from every device, will start to fail fairly quickly |
||||
after a 'clean install'. The reason why is because the JSON package |
||||
becomes too large and the connection times out. You might get better |
||||
results on a more powerfully spec'd server than the one used for the |
||||
exhibition but I have not tested this so I cannot confirm this. |
||||
|
||||
### 2. Three Light-Meters and Relays Specified but Only Two (of each) Used |
||||
|
||||
Ritherdon (the factory) has three welding booths so 'Personal Flash in |
||||
Real-Time' was designed with this in mind. Over the course of the |
||||
development process, the use of the third booth was not |
||||
needed/wanted. By that time, the code, database and models had already |
||||
been created. I decided to opt for the lazy option and keep the |
||||
references to the third booth instead of removing it because it was |
||||
not impeding on the system in any way. I was, also, cautious about the |
||||
chance of a change happening late into the development cycle were I |
||||
would need to put it back it. |
||||
|
After Width: | Height: | Size: 100 KiB |
|
After Width: | Height: | Size: 102 KiB |
|
After Width: | Height: | Size: 120 KiB |
@ -0,0 +1,20 @@
|
||||
digraph overview { |
||||
node [fontname = Arial]; |
||||
l1 -> server; |
||||
l2 -> server; |
||||
server -> r1; |
||||
server -> r2; |
||||
r1 -> server; |
||||
r2 -> server; |
||||
l1 [label = "Light Meter 1", color = lightblue, style = filled]; |
||||
l2 [label = "Light Meter 2", color = orange, style = filled]; |
||||
r1 [label = "Relay 1", color = lightblue, style = filled]; |
||||
r2 [label = "Relay 2", color = orange, style = filled ]; |
||||
server [label = "Midpoint (Server)"]; |
||||
subgraph cluster0 { |
||||
style = filled; |
||||
color = lightgrey; |
||||
r1; |
||||
r2; |
||||
} |
||||
} |
||||
|
After Width: | Height: | Size: 26 KiB |
|
After Width: | Height: | Size: 38 KiB |
|
After Width: | Height: | Size: 887 KiB |
@ -0,0 +1,287 @@
|
||||
# Return to Ritherdon: Relay |
||||
|
||||
Relay is one of three smaller projects which make-up the 'Personal |
||||
Flash in Real-Time' -- which is one artwork with the main 'Return to |
||||
Ritherdon' project.You should view the three smaller projects as one |
||||
project. And, for the purpose of this documentation, I will refer to |
||||
'Personal Flash in Real-Time' as a system instead of an artwork. |
||||
|
||||
For more information on the 'Return to Ritherdon' project, use the |
||||
following link: |
||||
|
||||
- [Return to Ritherdon Overview](https://git.abbether.net/return-to-ritherdon/rtr-docs) |
||||
|
||||
### 'Personal Flash in Real-Time': Project Overview |
||||
|
||||
The overall system ('Personal Flash in Real-Time') consists of three |
||||
separate/smaller projects. You should not view them as individual |
||||
pieces within the overall project. From an artwork point-of-view, |
||||
'Personal Flash in Real-Time' is one piece. The name of the software |
||||
projects are 'Light Meter' (which is this one), 'Midpoint' and |
||||
'Relay'. All three projects reside in their own git repositories. You |
||||
can find the repositories at the following links: |
||||
|
||||
- [Light Meter](https://git.abbether.net/return-to-ritherdon/light-meter) |
||||
- [Mid-Point](https://git.abbether.net/return-to-ritherdon/midpoint) |
||||
- [Relay](https://git.abbether.net/return-to-ritherdon/relay) |
||||
|
||||
The (technical) aim of the project is to turn a set of lights on at |
||||
the gallery when the welding machines are active in the welding booths |
||||
at Ritherdon. The solution we arrived at was a three-stage |
||||
process. The stages are as follows: |
||||
|
||||
1. Monitor the light levels in the welding booths at Ritherdon and |
||||
send that information to a sever (Light Meter). |
||||
2. Receive the light readings and store them in a database and make |
||||
them available for others to access (Midpoint). |
||||
3. Have the lights installed at the gallery connected to wi-fi enabled |
||||
relays which request the latest light readings from the server. If |
||||
the readings are above a certain threshold, have the light in the |
||||
gallery turn on (otherwise, turn off). The relays are responsible |
||||
for turning the lights on and off (Relay). |
||||
|
||||
Each step should require no human intervention. |
||||
|
||||
For more information on how each project accomplishes its task, please |
||||
use the (repo.) links above. Otherwise, here is an diagram to help |
||||
explain the three stages mentioned above. |
||||
|
||||
 |
||||
|
||||
## Hardware Specifications |
||||
|
||||
Here are a list of parts used in this project: |
||||
|
||||
- [Raspbian](https://www.raspberrypi.org/downloads/raspbian/) (You can |
||||
use the G.U.I. or "headless" version) |
||||
- [Raspberry Pi |
||||
4](https://www.raspberrypi.org/products/raspberry-pi-4-model-b/) (I |
||||
am assuming you have the appropriate power cable, S.D. cards Etc.) |
||||
- [Single Channel 5v Relay](https://www.amazon.co.uk/Dealikee-Module-Indicator-Channel-Arduino/dp/B08ZJ9T355/ref=sr_1_12?dchild=1&keywords=5v+relay+module&linkCode=gs3&qid=1635877670&qsid=262-0370227-8667213&sr=8-12&sres=B08YK9V3V6%2CB07RKH9KLM%2CB06XK6HCQC%2CB01H2D2RI0%2CB08MTD5BPJ%2CB07PZC9ZMM%2CB07CNR7K9B%2CB08ZJ9T355%2CB07V1YQQGL%2CB07MY2R2ML%2CB07G71S7VP%2CB09C2ZHXXP%2CB08GPF9FNX%2CB09CN81J32%2CB07SDLJSWB%2CB08YJ6TS29%2CB08V15SNZS%2CB09DS3DD1J%2CB08KWPMP2V%2CB07TTVYGC8&srpt=RELAY) |
||||
|
||||
## Points of Interest for Understanding How Relays work |
||||
|
||||
I have included this section if you are unfamiliar with what a relay |
||||
is, how it works and how it connects/works with a Raspberry Pi. If you |
||||
are already familiar with relays, you can skip this section. |
||||
|
||||
### Checking Your Raspberry Pi's Hardware Layout |
||||
|
||||
Because there are multiple versions of the Raspberry Pi, the layout of |
||||
the General Purpose Input/Output (G.P.I.O.) Pins differ. A quick way |
||||
to find out how the G.P.I.O. pins are laid out, for the Pi you are |
||||
currently working on, is to open a terminal and entering the following |
||||
command `pinout`. |
||||
|
||||
Doing this will lead to you seeing something similar to the image |
||||
below, |
||||
|
||||
 |
||||
|
||||
More information about this can be found at the following URL: |
||||
|
||||
- [Checking Raspberry Pi Board Version](https://www.raspberrypi-spy.co.uk/2012/09/checking-your-raspberry-pi-board-version/][Raspberry Pi Board Information) |
||||
|
||||
### Wiring-Up the Relay |
||||
|
||||
- [Wiring Single Channel Relay with Raspberry Pi](https://www.14core.com/wiring-single-channel-relay-with-raspberry-pi-on-wiringpi-python/) |
||||
|
||||
I used this article/blog post (linked above) as a starting-point for |
||||
the relay part of the project. It includes software written in C and |
||||
Python but I have stuck to just Python for this project. You can see |
||||
how the relay is wired-up to the Pi in the image below. |
||||
|
||||
 |
||||
|
||||
### General Overview of Controlling Relays |
||||
|
||||
- [Four Ways to Control Electronic Relays](https://makezine.com/2018/03/19/control-electronic-relays/) |
||||
|
||||
This is a primer for understanding how to control relays and the |
||||
various types of relays at your disposal. The list is not exhaustive |
||||
but is enough to get you going. |
||||
|
||||
- [YouTube Guide](https://www.youtube.com/watch?v=58XWVDnB7Ss) |
||||
|
||||
I find the guy in this video difficult to understand but he gets his |
||||
message across well enough. He explains how a relay works and how to |
||||
connect it to an *Arduino Board* and control a light bulb. If you are |
||||
not familiar with how relays work, this video should give you a good |
||||
grounding in it. /Note: This video does not use a Raspberry Pi so the |
||||
information is limited to just the relay and the light part of the |
||||
project. |
||||
|
||||
- [How to Set-up a 5v Relay](https://www.circuitbasics.com/setting-up-a-5v-relay-on-the-arduino/) |
||||
|
||||
The link above focuses on using an *Arduino Board* but you can |
||||
determine what pin does what. The example in the link, also, |
||||
includes a thermistor in its set-up which does not apply to this |
||||
project. The image below is taken from the site and |
||||
highlights what each pin is. |
||||
|
||||
 |
||||
|
||||
- **NO (Normally Open)**: In the normally open configuration, when the |
||||
relay receives a HIGH signal the 120-240V switch closes and allows |
||||
current to flow from the C terminal to the NO terminal. A LOW signal |
||||
deactivates the relay and stops the current. So if you want the HIGH |
||||
signal to turn ON the relay, use the normally open terminal. See |
||||
images below for further information. |
||||
- **NC (Normally Closed)**: In the normally closed configuration, a |
||||
HIGH signal opens the switch and interrupts the 120-240V current. A |
||||
LOW signal closes the switch and allows current to flow from the C |
||||
terminal to the NC terminal. Therefore, if you want the HIGH signal |
||||
to turn OFF the 120-240V current, use the normally closed |
||||
terminal. See images below for further information. |
||||
|
||||
 |
||||
|
||||
 |
||||
|
||||
## Project Set-up |
||||
|
||||
Relay consists of two parts: hardware and software. The hardware part |
||||
focuses on the electronics attached to the Raspberry Pi 4 and the |
||||
software side focuses on installing software dependencies onto the |
||||
operating system and 'maintenance' tasks for sustained use of the |
||||
device (whilst in operation). For the code written specifically for |
||||
this project, please use the following link: |
||||
|
||||
- [Relay Software Repository](https://git.abbether.net/return-to-ritherdon/relay) |
||||
|
||||
### Initial Raspbian Set-up |
||||
|
||||
Upon the initial installation of Raspbian on to the Pi, you need to make sure the following is established: |
||||
|
||||
- The username is `rtrp`. |
||||
- The host-name is `gallery#` (where "#" is either 1 and 2). |
||||
- The Pi is set to auto-login with the `rtrp` account. |
||||
|
||||
You can set the Pi up to automatically login to the desktop but the |
||||
recommended option is to login to a "headless" environment |
||||
(I.E. console-mode). Remember, you can only log into the desktop |
||||
environment if your version of Raspbian has one. The final version of |
||||
this project does not expect one. |
||||
|
||||
### Hardware Preparations |
||||
|
||||
### Network Connections |
||||
|
||||
Before installing Raspberry Pi in its final location |
||||
(gallery/exhibition), make sure it can connect to the galleries |
||||
internet - either via Wi-Fi or Ethernet cable. If you use an Ethernet |
||||
cable, you do not need to do anything, but Wi-Fi requires a little |
||||
work on the command-line (if you are using a 'headless' version of |
||||
Raspbian). If you are unsure how to connect to a router via Wi-Fi, use |
||||
the following link to learn how: |
||||
|
||||
- [Raspbian Wi-Fi Tutorial](https://www.raspberrypi.org/documentation/configuration/wireless/wireless-cli.md) |
||||
|
||||
### Relay Set-up |
||||
|
||||
To connect the relay to the Raspberry Pi, refer to the following image: |
||||
|
||||
- [the image above](https://git.abbether.net/return-to-ritherdon/rtr-docs/src/branch/unstable/relay/rtr-relay.md#wiring-up-the-relay) |
||||
|
||||
### Software Preparations |
||||
|
||||
Depending on what version of Linux/Raspbian you are running, you might |
||||
need to install some dependencies. I have listed the common ones I |
||||
came across whilst developing this project. But, you might need to |
||||
rely on your own cunning to track down missing dependencies. |
||||
|
||||
```bash |
||||
# Don't forget to apt update and upgrade first... |
||||
sudo apt install python3-pip |
||||
|
||||
sudo pip3 install requests |
||||
sudo pip3 install RPi.GPIO |
||||
|
||||
# You might need to install RPi.GPIO via apt |
||||
sudo apt install python3-rpi.gpio |
||||
|
||||
# I will explain why this is here below... |
||||
mkdir ~/repos |
||||
``` |
||||
|
||||
**Note: I decided not to create/use a (Python) virtual environment |
||||
because of the projects objectives. I expect the software in this |
||||
repository to run on an unmanned machine with only one task to |
||||
complete. The environment this project will run in/on will not change |
||||
throughout the course of the exhibition. So, the redundancies afforded |
||||
by the virtual environment are not needed.** |
||||
|
||||
When you clone this repository, you need to make sure you clone it |
||||
into the following location: `/home/rtrp/repos/relay/`. From |
||||
there, run the following command, |
||||
|
||||
```bash |
||||
# This must be the first thing you run after you have cloned |
||||
# the repository. |
||||
. ~/repos/relay/make-log-files.sh |
||||
``` |
||||
|
||||
You can test the code is working properly by running it. You can do |
||||
that by entering `sudo python3 ~/repos/relay/reply.py`. This is |
||||
assuming the server specified in `reply.py` is set-up and working as |
||||
intended. The server is developed in the 'Midpoint' project |
||||
repository. Links for 'Midpoint' are as follows: |
||||
|
||||
- [Midpoint Code](https://git.abbether.net/return-to-ritherdon/relay/src/branch/master) |
||||
- [Midpoint Documentation](https://git.abbether.net/return-to-ritherdon/rtr-docs/src/branch/master/midpoint) |
||||
|
||||
Note: For some reason, I had trouble running `relay.py` without |
||||
sudo. I would sometimes get an error message saying "RPi.GPIO is not |
||||
available/installed" (paraphrased). If you manage to get it working |
||||
without the use of sudo, remain as you were. Otherwise, keep a mental |
||||
note of this if you come across the problem. |
||||
|
||||
### Set-Up Program as a Cronjob |
||||
|
||||
When you are ready to run this project as intended, you can set-up a |
||||
cron-job for it. To do so enter `sudo crontab -e` into the console (see |
||||
note about sudo above). You might need to select an editor if this is |
||||
your first time setting up a cron-job. I tend to go for Nano -- which |
||||
is option "1" most of the time. When the crontab file opens, enter the |
||||
following commands at the bottom of the file, |
||||
|
||||
```bash |
||||
@reboot bash /home/rtrp/repos/relay/startup.sh & |
||||
00 18 * * * /home/rtrp/repos/relay/shutdown.sh |
||||
``` |
||||
|
||||
These tasks make the Raspberry Pi send a message to the sever to |
||||
indicate its/their status ("on" or "off") and makes the `startup.sh` |
||||
script run. At this point, you should be able to walk away and let the |
||||
Pi do its thing. This is assuming the server is up and running and the |
||||
Pi is connected to the world-wide-web. If all is successful, you will |
||||
notice the Pi will turn itself off at 18:00 (6 p.m.) and will start |
||||
receiving reading when you turn it on without any input from |
||||
you. Unfortunately, the Pi can only manage the shutdown procedure on |
||||
its own. You will need to turn it on. (This has been accounted whilst |
||||
the exhibition is open.) |
||||
|
||||
This next part is optional. To make sure the Pi sends a "powering |
||||
down" message to the server, I tend you create an alias called |
||||
`powerdown`. When you type this into the console, it runs the |
||||
`shutdown.sh` script -- which has the shutdown command within it. To |
||||
make the alias permanent, enter `alias='~/repos/relay/shutdown.sh` |
||||
into `~/.bashrc`. This is easier to test the bespoke shutdown |
||||
procedure is working as intended. You can, also, adjust the time in |
||||
the crontab or run the script by running the script like you normally |
||||
would but I find them to be frustrating to do in this instance. |
||||
|
||||
### Running the Program Manually (Quick Reference) |
||||
|
||||
If you have already completed the other installation/set-up tasks, use |
||||
the code below. |
||||
|
||||
```bash |
||||
# This assumes you have cloned the repository and completed the other |
||||
# installation tasks. |
||||
sudo python3 ~/repos/relay/reply.py |
||||
``` |
||||
|
||||
(Note: This is here so I have something to quickly refer to after I've |
||||
forgot how the Relay works -- because I've not used it for a long |
||||
time.) |
||||
Reference in new issue