diff --git a/relay/rtr-relay.md b/relay/rtr-relay.md index ba9ed9d..baadde5 100644 --- a/relay/rtr-relay.md +++ b/relay/rtr-relay.md @@ -91,8 +91,6 @@ 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. -#+Caption: Wiring Diagram for the Relay Project -#+Name: wiring-diagram-relay ![Wiring Diagram Relay](attachments/wiring-diagram-relay.png) ### General Overview of Controlling Relays @@ -128,13 +126,13 @@ highlights what each pin is. 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 - /figure [[no-configuration]]/ 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 + 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 /figure [[nc-configuration]]/ for further information. + terminal. See images below for further information. ![Relay Normally Open Layout](attachments/5v-relay-normally-open-layout.png) @@ -142,16 +140,148 @@ highlights what each pin is. ## Project Set-up -This section needs to be written. +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 +### 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 -### Running the Program +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 not +I've forgot how the Relay works -- because I've not used it for a long +time.)