# 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.

![Main Project Architecture](attachments/main-proj-architecture.png)

## 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,

![pinout-terminal](attachments/pinout-terminal.png)

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.

![Wiring Diagram Relay](attachments/wiring-diagram-relay.png)

### 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.

![Relay Pins Layout](attachments/5v-relay-pins-layout.png)

- **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.

![Relay Normally Open Layout](attachments/5v-relay-normally-open-layout.png)

![Relay Normally Closed Layout](attachments/5v-relay-normally-closed-layout.png)

## 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.)